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 ", uint32_t " flags );
11 .BI "struct llapi_layout *llapi_layout_get_by_fid(const char *"lustre_path ,
12 .BI " const struct lu_fid *"fid ,
13 .BI " uint32_t " flags );
15 .BI "struct llapi_layout *llapi_layout_get_by_path(const char *"path ,
16 .BI " uint32_t " flags );
18 .BI "struct llapi_layout *llapi_layout_get_by_xattr(void *"lov_xattr ,
19 .BI " ssize_t " lov_xattr_size ,
20 .BI " uint32_t " xattr_flags );
24 .BR llapi_layout_get_by_xattr() ,
25 .BR llapi_layout_get_by_fd() ,
26 .BR llapi_layout_get_by_fid() ,
28 .BR llapi_layout_get_by_path()
29 return a pointer to a newly-allocated
30 .B struct llapi_layout
31 containing the layout information for the file referenced by
38 .B struct llapi_layout
39 is an opaque entity containing the layout information for a file in a
40 Lustre filesystem. Its internal structure should not be directly
41 accessed by an application. See
43 The pointer should be freed with
44 .B llapi_layout_free()
45 when it is no longer needed.
48 .BR llapi_layout_get_by_xattr() ,
50 is a Lustre layout extended attribute (LOV EA) from a file or directory in
51 a Lustre filesystem. The
53 should be the raw xattr without being byte-swapped, since this function will
57 .BR llapi_layout_get_by_fd() ,
59 is a valid open file descriptor for a file or directory in a Lustre
63 .BR llapi_layout_get_by_fid() ,
66 serves to identify the Lustre filesystem containing the file
69 It is typically the filesystem root, 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
86 to control how a layout is retrieved. Currently
87 .B llapi_layout_get_by_path()
88 accepts only one flag, and
89 .B llapi_layout_get_by_fd()
91 .B llapi_layout_get_by_fid()
92 do not accept any flags. The list of flags that can be used in
96 .SM LAYOUT_GET_EXPECTED
97 Unspecified attribute values are replaced by the literal default values
98 that will be assigned when the file is created or first written to.
99 A default value is inherited from the parent directory if the attribute
100 is specified there, otherwise it is inherited from the filesystem root.
101 This flag is only recognized by
102 .BR llapi_layout_get_by_path() .
103 Unspecified attributes may belong to directories and never-written-to
106 By default, layouts report the abstract value
107 .B LLAPI_LAYOUT_DEFAULT
108 to indicate an unspecified attribute. Use
109 .B LAYOUT_GET_EXPECTED
110 to discover the expected literal values for new files in a given
111 directory. Do not use it if you need to distinguish between specified
112 and unspecified attributes. The flag has no effect if
114 names a file or directory with a fully specified layout.
116 For concreteness, consider a Lustre filesystem with a default stripe
117 size of 1048576 and a default stripe count of 1. A user sets the stripe
118 count for directory D to 2 (thus overriding the filesystem-wide
119 default) but leaves the stripe size unspecified. Newly created files in
120 D inherit a stripe count of 2 from D and a stripe size of 1048576 from
121 the filesystem default. The layout of D returned by
122 .B llapi_layout_get_by_path(D, 0)
123 has the abstract stripe size value
124 .BR LLAPI_LAYOUT_DEFAULT ,
125 since stripe size is unspecified, while
126 .B llapi_layout_get_by_path(D, LAYOUT_GET_EXPECTED)
127 reports the literal value 1048576. Both forms report a stripe count
128 of 2, since that attribute is specified.
130 The list of flags that can be used in
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
141 flag should be cleared if the xattr belongs to a directory.
146 flag is set, this function will use a temporary buffer for byte swapping
147 when necessary, leaving
149 untouched. Otherwise, the byte swapping will be done to the
154 .BR llapi_layout_get_by_fd() ,
155 .BR llapi_layout_get_by_fid() ,
157 .B llapi_layout_get_by_path()
158 return a valid pointer on success or
162 set to an approporiate error code.
166 Insufficient storage space is available.
169 File does not reside on a Lustre filesystem.
176 An invalid argument was specified.
179 The kernel returned less than the expected amount of data.
181 .BR llapi_layout_file_open (3),
182 .BR llapi_path2fid (3),
183 .BR llapi_layout (7),