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),
54 .BR llapi_layout_get_by_fid (3)
57 To access attribute values from
58 .B struct llapi_layout
60 .B llapi_layout_*_get (3)
63 To free the previously allocated layout memory use
64 .BR llapi_layout_free (3).
66 Using this interface to create a file with composite layout consists of the
69 Allocate first layout component with
70 .BR llapi_layout_alloc (3).
72 Assign attribute values using the
73 .B llapi_layout_*_set (3)
76 Allocate second layout component with
77 .BR llapi_layout_alloc (3).
79 Add the second layout into the first one using
80 .BR llapi_layout_comp_add (3).
82 Assign attribute values to second layout using the
83 .BR llapi_layout_*_set (3)
86 Repeat above two steps to add more components.
89 .BR llapi_layout_file_create (3).
91 Free the layout memory using
92 .BR llapi_layout_free (3).
94 Example 1: Create file with specified layout, then query the layout attributes.
99 struct llapi_layout *layout = llapi_layout_alloc();
101 /* Set attributes of layout */
102 llapi_layout_stripe_count_set(layout, count);
103 llapi_layout_stripe_size_set(layout, size);
105 /* Create file with specified layout */
106 fd = llapi_layout_file_create(path, 0, 0640, layout);
109 llapi_layout_free(layout);
111 /* Retrieve layout from file */
112 layout = llapi_layout_get_by_path(path, 0);
114 /* Get attributes of layout */
115 llapi_layout_stripe_size_get(layout, &size),
116 llapi_layout_stripe_count_get(layout, &count);
119 llapi_layout_free(layout);
123 Example 2: Create file with composite layout.
127 struct llapi_layout *head, *comp;
129 /* Create first component */
130 head = llapi_layout_alloc();
131 llapi_layout_stripe_count_set(head, 1);
132 llapi_layout_stripe_size_set(head, 1048576);
133 llapi_layout_comp_extent_set(NULL, head, 0, 2097152); //[0, 2M)
135 /* Create the second component */
136 comp = llapi_layout_alloc();
137 llapi_layout_comp_add(head, comp);
138 llapi_layout_comp_extent_set(head, comp, 2097152, 67108864); //[2M, 64M)
139 llapi_layout_stripe_count_set(comp, 4);
141 /* Create the third component */
142 comp = llapi_layout_alloc();
143 llapi_layout_comp_add(head, comp);
144 llapi_layout_comp_extent_set(head, comp, 67108864,
145 (u_int64t)-1); //[64M, EOF)
146 llapi_layout_stripe_count_set(comp, LLAPI_LAYOUT_WIDE);
148 /* Create file with specified composite layout */
149 fd = llapi_layout_file_create(path, 0, 0640, head);
152 llapi_layout_free(head);
156 Example 3: Traverse components of a composite layout.
160 /* Retrieve composite layout from file */
161 layout = llapi_layout_get_by_path(path, 0);
163 /* Move cursor to the first component */
164 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
166 /* Traverse all components */
168 /* Get attributes of each component */
169 llapi_layout_stripe_count_get(comp, &count);
170 llapi_layout_stripe_size_get(comp, &size);
171 llapi_layout_comp_extent_get(layout, &start, &end);
174 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
178 llapi_layout_free(layout);
183 Setting the OST index number is only supported for stripe number 0.
185 The RAID pattern may only be set to 0.
190 .BR llapi_layout_alloc (3),
191 .BR llapi_layout_file_create (3),
192 .BR llapi_layout_file_open (3),
193 .BR llapi_layout_free (3),
194 .BR llapi_layout_get_by_fd (3),
195 .BR llapi_layout_get_by_fid (3),
196 .BR llapi_layout_get_by_path (3),
197 .BR llapi_layout_ost_index_get (3),
198 .BR llapi_layout_ost_index_set (3),
199 .BR llapi_layout_pattern_get (3),
200 .BR llapi_layout_pattern_set (3),
201 .BR llapi_layout_pool_name_get (3),
202 .BR llapi_layout_pool_name_set (3),
203 .BR llapi_layout_stripe_count_get (3),
204 .BR llapi_layout_stripe_count_set (3),
205 .BR llapi_layout_stripe_size_get (3),
206 .BR llapi_layout_stripe_size_set (3),
207 .BR llapi_layout_comp_extent_get (3),
208 .BR llapi_layout_comp_extent_set (3),
209 .BR llapi_layout_comp_flags_get (3),
210 .BR llapi_layout_comp_flags_set (3),
211 .BR llapi_layout_comp_flags_clear (3),
212 .BR llapi_layout_comp_id_get (3),
213 .BR llapi_layout_comp_add (3),
214 .BR llapi_layout_comp_del (3),
215 .BR llapi_layout_comp_use (3),
216 .BR llapi_layout_comp_use_id (3),
217 .BR llapi_layout_file_comp_add (3),
218 .BR llapi_layout_file_comp_del (3),
220 .BR lfs-setstripe (1)