1 .TH llapi_layout 7 "2013 Oct 31" "Lustre User API"
3 llapi_layout \- abstract interface to the layout of a Lustre file
6 .B #include <lustre/lustreapi.h>
11 family of functions functions provides an abstract interface to
12 manipulating the layout information of a file in a Lustre filesystem.
13 Layouts are represented by the opaque data type
14 .B struct llapi_layout
15 which is passed as a handle to the various functions.
17 A layout has a number of attributes that describe how a file's data are
18 stored in the filesystem. These include stripe count, stripe size, RAID
19 pattern, pool name, and the OST index associated with each stripe. In more
20 complex layouts, a file may have multiple components that describe a different
21 layout for separate regions of the file. Refer to the Lustre Operations Manual
22 for detailed descriptions of these attributes. For each attribute, there
23 exists a pair of functions with the suffixes
27 that are used to read and assign the attribute value in a given layout.
29 Using this interface to create a file might consist of the following steps.
34 .BR llapi_layout_alloc (3).
36 Assign attribute values using the
37 .B llapi_layout_*_set (3)
41 .BR llapi_layout_file_create (3).
43 Free the layout memory using
44 .BR llapi_layout_free (3).
46 Similarly, these steps might be used to read a file layout:
48 One can allocate and initialize a new
50 from an existing file with one of the
51 .BR llapi_layout_get_by_path (3),
52 .BR llapi_layout_get_by_fd (3),
53 .BR llapi_layout_get_by_fid (3),
55 .BR llapi_layout_get_by_xattr (3)
58 To access attribute values from
59 .B struct llapi_layout
61 .B llapi_layout_*_get (3)
64 To free the previously allocated layout memory use
65 .BR llapi_layout_free (3).
67 Using this interface to create a file with composite layout consists of the
70 Allocate first layout component with
71 .BR llapi_layout_alloc (3).
73 Assign attribute values using the
74 .B llapi_layout_*_set (3)
77 Allocate second layout component with
78 .BR llapi_layout_alloc (3).
80 Add the second layout into the first one using
81 .BR llapi_layout_comp_add (3).
83 Assign attribute values to second layout using the
84 .BR llapi_layout_*_set (3)
87 Repeat above two steps to add more components.
90 .BR llapi_layout_file_create (3).
92 Free the layout memory using
93 .BR llapi_layout_free (3).
95 Example 1: Create file with specified layout, then query the layout attributes.
100 struct llapi_layout *layout = llapi_layout_alloc();
102 /* Set attributes of layout */
103 llapi_layout_stripe_count_set(layout, count);
104 llapi_layout_stripe_size_set(layout, size);
106 /* Create file with specified layout */
107 fd = llapi_layout_file_create(path, 0, 0640, layout);
110 llapi_layout_free(layout);
112 /* Retrieve layout from file */
113 layout = llapi_layout_get_by_path(path, 0);
115 /* Get attributes of layout */
116 llapi_layout_stripe_size_get(layout, &size),
117 llapi_layout_stripe_count_get(layout, &count);
120 llapi_layout_free(layout);
124 Example 2: Create file with composite layout.
128 struct llapi_layout *head, *comp;
130 /* Create first component */
131 head = llapi_layout_alloc();
132 llapi_layout_stripe_count_set(head, 1);
133 llapi_layout_stripe_size_set(head, 1048576);
134 llapi_layout_comp_extent_set(NULL, head, 0, 2097152); //[0, 2M)
136 /* Create the second component */
137 comp = llapi_layout_alloc();
138 llapi_layout_comp_add(head, comp);
139 llapi_layout_comp_extent_set(head, comp, 2097152, 67108864); //[2M, 64M)
140 llapi_layout_stripe_count_set(comp, 4);
142 /* Create the third component */
143 comp = llapi_layout_alloc();
144 llapi_layout_comp_add(head, comp);
145 llapi_layout_comp_extent_set(head, comp, 67108864,
146 (u_int64t)-1); //[64M, EOF)
147 llapi_layout_stripe_count_set(comp, LLAPI_LAYOUT_WIDE);
149 /* Create file with specified composite layout */
150 fd = llapi_layout_file_create(path, 0, 0640, head);
153 llapi_layout_free(head);
157 Example 3: Traverse components of a composite layout.
161 /* Retrieve composite layout from file */
162 layout = llapi_layout_get_by_path(path, 0);
164 /* Move cursor to the first component */
165 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
167 /* Traverse all components */
169 /* Get attributes of each component */
170 llapi_layout_stripe_count_get(comp, &count);
171 llapi_layout_stripe_size_get(comp, &size);
172 llapi_layout_comp_extent_get(layout, &start, &end);
175 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
179 llapi_layout_free(layout);
184 Setting the OST index number is only supported for stripe number 0.
186 The RAID pattern may only be set to 0.
191 .BR llapi_layout_alloc (3),
192 .BR llapi_layout_file_create (3),
193 .BR llapi_layout_file_open (3),
194 .BR llapi_layout_free (3),
195 .BR llapi_layout_get_by_fd (3),
196 .BR llapi_layout_get_by_fid (3),
197 .BR llapi_layout_get_by_path (3),
198 .BR llapi_layout_get_by_xattr (3),
199 .BR llapi_layout_ost_index_get (3),
200 .BR llapi_layout_ost_index_set (3),
201 .BR llapi_layout_pattern_get (3),
202 .BR llapi_layout_pattern_set (3),
203 .BR llapi_layout_pool_name_get (3),
204 .BR llapi_layout_pool_name_set (3),
205 .BR llapi_layout_stripe_count_get (3),
206 .BR llapi_layout_stripe_count_set (3),
207 .BR llapi_layout_stripe_size_get (3),
208 .BR llapi_layout_stripe_size_set (3),
209 .BR llapi_layout_comp_extent_get (3),
210 .BR llapi_layout_comp_extent_set (3),
211 .BR llapi_layout_comp_flags_get (3),
212 .BR llapi_layout_comp_flags_set (3),
213 .BR llapi_layout_comp_flags_clear (3),
214 .BR llapi_layout_comp_id_get (3),
215 .BR llapi_layout_comp_add (3),
216 .BR llapi_layout_comp_del (3),
217 .BR llapi_layout_comp_use (3),
218 .BR llapi_layout_comp_use_id (3),
219 .BR llapi_layout_file_comp_add (3),
220 .BR llapi_layout_file_comp_del (3),
222 .BR lfs-setstripe (1)