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 lustre_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 );
20 .BR llapi_layout_get_by_fd() ,
21 .BR llapi_layout_get_by_fid() ,
23 .BR llapi_layout_get_by_path()
24 return a pointer to a newly-allocated
25 .B struct llapi_layout
26 containing the layout information for the file referenced by
32 .B struct llapi_layout
33 is an opaque entity containing the layout information for a file in a
34 Lustre filesystem. Its internal structure should not be directly
35 accessed by an application. See
37 The pointer should be freed with
38 .B llapi_layout_free()
39 when it is no longer needed.
42 .BR llapi_layout_get_by_fd() ,
44 is a valid open file descriptor for a file or directory in a Lustre
48 .BR llapi_layout_get_by_fid() ,
51 serves to identify the Lustre filesystem containing the file
54 It is typically the filesystem root, but may also be any path beneath
55 the root. Use the function
56 .BR llapi_path2fid (3)
59 associated with a given path.
62 .B llapi_layout_get_by_path()
65 argument that names a file or directory in a Lustre filesystem.
67 Zero or more flags may be bitwise-or'd together in
69 to control how a layout is retrieved. Currently
70 .B llapi_layout_get_by_path()
71 accepts only one flag, and
72 .B llapi_layout_get_by_fd()
74 .B llapi_layout_get_by_fid()
75 do not accept any flags. The list of flags is as follows:
77 .SM LAYOUT_GET_EXPECTED
78 Unspecified attribute values are replaced by the literal default values
79 that will be assigned when the file is created or first written to.
80 A default value is inherited from the parent directory if the attribute
81 is specified there, otherwise it is inherited from the filesystem root.
82 This flag is only recognized by
83 .BR llapi_layout_get_by_path() .
84 Unspecified attributes may belong to directories and never-written-to
87 By default, layouts report the abstract value
88 .B LLAPI_LAYOUT_DEFAULT
89 to indicate an unspecified attribute. Use
90 .B LAYOUT_GET_EXPECTED
91 to discover the expected literal values for new files in a given
92 directory. Do not use it if you need to distinguish between specified
93 and unspecified attributes. The flag has no effect if
95 names a file or directory with a fully specified layout.
97 For concreteness, consider a Lustre filesystem with a default stripe
98 size of 1048576 and a default stripe count of 1. A user sets the stripe
99 count for directory D to 2 (thus overriding the filesystem-wide
100 default) but leaves the stripe size unspecified. Newly created files in
101 D inherit a stripe count of 2 from D and a stripe size of 1048576 from
102 the filesystem default. The layout of D returned by
103 .B llapi_layout_get_by_path(D, 0)
104 has the abstract stripe size value
105 .BR LLAPI_LAYOUT_DEFAULT ,
106 since stripe size is unspecified, while
107 .B llapi_layout_get_by_path(D, LAYOUT_GET_EXPECTED)
108 reports the literal value 1048576. Both forms report a stripe count
109 of 2, since that attribute is specified.
112 .BR llapi_layout_get_by_fd() ,
113 .BR llapi_layout_get_by_fid() ,
115 .B llapi_layout_get_by_path()
116 return a valid pointer on success or
120 set to an approporiate error code.
124 Insufficient storage space is available.
127 File does not reside on a Lustre filesystem.
134 An invalid argument was specified.
137 The kernel returned less than the expected amount of data.
139 .BR llapi_layout_file_open (3),
140 .BR llapi_path2fid (3),
141 .BR llapi_layout (7),