1 .TH llapi_layout_get_by_fd 3 "2013 Oct 31" "Lustre User API"
3 llapi_layout_get_by_fd, llapi_layout_get_by_fid, llapi_layout_get_by_path, \-
4 obtain the layout of a Lustre file
7 .B #include <lustre/lustreapi.h>
9 .BI "struct llapi_layout *llapi_layout_get_by_fd(int " fd ,
10 .BI " enum llapi_layout_get_flags " flags );
12 .BI "struct llapi_layout *llapi_layout_get_by_fid(const char *"lustre_path ,
13 .BI " const struct lu_fid *"fid ,
14 .BI " enum llapi_layout_get_flags " flags );
16 .BI "struct llapi_layout *llapi_layout_get_by_path(const char *"path ,
17 .BI " enum llapi_layout_get_flags " flags );
19 .BI "struct llapi_layout *llapi_layout_get_by_xattr(void *"lov_xattr ,
20 .BI " ssize_t " lov_xattr_size ,
21 .BI " enum llapi_layout_get_flags " flags );
26 .BR llapi_layout_get_by_xattr() ,
27 .BR llapi_layout_get_by_fd() ,
28 .BR llapi_layout_get_by_fid() ,
30 .BR llapi_layout_get_by_path()
31 return a pointer to a newly-allocated
32 .B struct llapi_layout
33 containing the layout information for the file referenced by
40 .B struct llapi_layout
41 is an opaque entity containing the layout information for a file in a
42 Lustre filesystem. Its internal structure should not be directly
43 accessed by an application. See
45 The pointer should be freed with
46 .B llapi_layout_free()
47 when it is no longer needed.
50 .BR llapi_layout_get_by_xattr() ,
52 is a Lustre layout extended attribute (LOV EA) from a file or directory in
53 a Lustre filesystem. The
55 should be the raw xattr without being byte-swapped, since this function will
56 swap it to the local machine endianness properly.
59 .BR llapi_layout_get_by_fd() ,
61 is a valid open file descriptor for a file or directory in a Lustre
65 .BR llapi_layout_get_by_fid() ,
67 identifies the Lustre filesystem containing the file represented by
69 It is typically the filesystem root directory, but may also be any path beneath
70 the root. Use the function
71 .BR llapi_path2fid (3)
74 associated with a given path.
77 .B llapi_layout_get_by_path()
80 argument that names a file or directory in a Lustre filesystem.
82 Zero or more flags may be bitwise-or'd together in
84 to control how a layout is retrieved. Currently
85 .B llapi_layout_get_by_fd()
87 .B llapi_layout_get_by_fid()
88 do not accept any values for
91 .B llapi_layout_get_by_path()
92 accepts only one flag as follows:
94 .SM LLAPI_LAYOUT_GET_EXPECTED
95 Unspecified attribute values are replaced by the literal default values
96 that will be assigned when the file is created or first written to.
97 A default value is inherited from the parent directory if the attribute
98 is specified there, otherwise it is inherited from the filesystem root.
99 This flag is only recognized by
100 .BR llapi_layout_get_by_path() .
101 Unspecified attributes may belong to directories and never-written-to
104 By default, layouts report the abstract value
105 .B LLAPI_LAYOUT_DEFAULT
106 to indicate an unspecified attribute. Use
107 .B LLAPI_LAYOUT_GET_EXPECTED
108 to discover the expected literal values for new files in a given
109 directory. Do not use it if you need to distinguish between specified
110 and unspecified attributes. The flag has no effect if
112 names a file or directory with a fully specified layout.
114 For concreteness, consider a Lustre filesystem with a default stripe
115 size of 1048576 and a default stripe count of 1. A user sets the stripe
116 count for directory D to 2 (thus overriding the filesystem-wide
117 default) but leaves the stripe size unspecified. Newly created files in
118 D inherit a stripe count of 2 from D and a stripe size of 1048576 from
119 the filesystem default. The layout of D returned by
120 .B llapi_layout_get_by_path(D, 0)
121 has the abstract stripe size value
122 .BR LLAPI_LAYOUT_DEFAULT ,
123 since stripe size is unspecified, while
124 .B llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED)
125 reports the literal value 1048576. Both forms report a stripe count
126 of 2, since that attribute is specified.
131 .B llapi_layout_get_by_xattr()
134 .SM LLAPI_LAYOUT_GET_CHECK
136 .B LLAPI_LAYOUT_GET_CHECK
137 flag is set, this function will check whether the objects count in lum
138 is consistent with the stripe count in lum. This check only apply to
139 regular files, so it should not be passed if the xattr is a default
140 layout from a directory.
142 .SM LLAPI_LAYOUT_GET_COPY
144 .B LLAPI_LAYOUT_GET_COPY
145 flag is set, this function will use a temporary buffer for byte swapping
146 when necessary, leaving
148 unmodified. Otherwise, the byte swapping will be done to the fields of the
152 When using these functions to copy an existing file's layout to create a
154 .B llapi_layout_file_open (3)
155 for mirroring, migration, or as the template for a new file,
156 .BR llapi_layout_ost_index_reset (3)
157 should be called to reset the OST index values for each component, so that
158 the file copy is not created on exactly the same OSTs as the original file.
160 These functions return a valid pointer on success or
164 set to an approporiate error code.
168 Insufficient storage space is available.
171 File does not reside on a Lustre filesystem.
178 An invalid argument was specified.
181 The kernel returned less than the expected amount of data.
183 .BR llapi_layout_file_open (3),
184 .BR llapi_layout_ost_index_reset (3),
185 .BR llapi_path2fid (3),
186 .BR llapi_layout (7),