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
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. Refer
20 to the Lustre Operations Manual for detailed descriptions of these
21 attributes. For each attribute, there exists a pair of functions with
26 that are used to read and assign the attribute value in a given layout.
28 Using this interface to create a file might consist of the following steps.
30 Allocate a layout with
31 .BR llapi_layout_alloc (3).
33 Assign attribute values using the
34 .B llapi_layout_*_set (3)
38 .BR llapi_layout_file_create (3).
40 Free the layout memory using
41 .BR llapi_layout_free (3).
43 Similarly, these steps might be used to read a file layout:
45 Obtain the layout with
46 .BR llapi_layout_get_by_path (3),
47 .BR llapi_layout_get_by_fd (3),
49 .BR llapi_layout_get_by_fid (3).
51 Read attribute values using the
52 .B llapi_layout_*_get (3)
55 Free the layout memory using
56 .BR llapi_layout_free (3).
58 Using this interface to create a file with composite layout consists of the
61 Allocate first layout component with
62 .BR llapi_layout_alloc (3).
64 Assign attribute values using the
65 .B llapi_layout_*_set (3)
68 Allocate second layout component with
69 .BR llapi_layout_alloc (3).
71 Add the second layout into the first one using
72 .BR llapi_layout_comp_add (3).
74 Assign attribute values to second layout using the
75 .BR llapi_layout_*_set (3)
78 Repeat above two steps to add more components.
81 .BR llapi_layout_file_create (3).
83 Free the layout memory using
84 .BR llapi_layout_free (3).
86 Example 1: Create file with specified layout, then query the layout attributes.
91 layout = llapi_layout_alloc();
93 /* Set attributes of layout */
94 llapi_layout_stripe_count_set(layout, count);
95 llapi_layout_stripe_size_set(layout, size);
97 /* Create file with specified layout */
98 fd = llapi_layout_file_create(path, 0, 0640, layout);
101 llapi_layout_free(layout);
103 /* Retrieve layout from file */
104 layout = llapi_layout_get_by_path(path, 0);
106 /* Get attributes of layout */
107 llapi_layout_stripe_size_get(layout, &size),
108 llapi_layout_stripe_count_get(layout, &count);
111 llapi_layout_free(layout);
115 Example 2: Create file with composite layout.
119 /* Create first component */
120 head = llapi_layout_alloc();
121 llapi_layout_stripe_count_set(head, 1);
122 llapi_layout_stripe_size_set(head, 1048576);
123 llapi_layout_comp_extent_set(NULL, head, 0, 2097152); //[0, 2M)
125 /* Create the second component */
126 comp = llapi_layout_alloc();
127 llapi_layout_comp_add(head, comp);
128 llapi_layout_comp_extent_set(head, comp, 2097152, 67108864); //[2M, 64M)
129 llapi_layout_stripe_count_set(comp, 4);
131 /* Create the third component */
132 comp = llapi_layout_alloc();
133 llapi_layout_comp_add(head, comp);
134 llapi_layout_comp_extent_set(head, comp, 67108864,
135 (u_int64t)-1); //[64M, EOF)
136 llapi_layout_stripe_count_set(comp, LLAPI_LAYOUT_WIDE);
138 /* Create file with specified composite layout */
139 fd = llapi_layout_file_create(path, 0, 0640, head);
142 llapi_layout_free(head);
146 Example 3: Traverse components of a composite layout.
150 /* Retrieve composite layout from file */
151 layout = llapi_layout_get_by_path(path, 0);
153 /* Move cursor to the first component */
154 rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_FIRST);
156 /* Traverse all components */
158 /* Get attributes of each component */
159 llapi_layout_stripe_count_get(comp, &count);
160 llapi_layout_stripe_size_get(comp, &size);
161 llapi_layout_comp_extent_get(layout, &start, &end);
164 rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_NEXT);
168 llapi_layout_free(layout);
173 Setting the OST index number is only supported for stripe number 0.
175 The RAID pattern may only be set to 0.
180 .BR llapi_layout_alloc (3),
181 .BR llapi_layout_file_create (3),
182 .BR llapi_layout_file_open (3),
183 .BR llapi_layout_free (3),
184 .BR llapi_layout_get_by_fd (3),
185 .BR llapi_layout_get_by_fid (3),
186 .BR llapi_layout_get_by_path (3),
187 .BR llapi_layout_ost_index_get (3),
188 .BR llapi_layout_ost_index_set (3),
189 .BR llapi_layout_pattern_get (3),
190 .BR llapi_layout_pattern_set (3),
191 .BR llapi_layout_pool_name_get (3),
192 .BR llapi_layout_pool_name_set (3),
193 .BR llapi_layout_stripe_count_get (3),
194 .BR llapi_layout_stripe_count_set (3),
195 .BR llapi_layout_stripe_size_get (3),
196 .BR llapi_layout_stripe_size_set (3),
197 .BR llapi_layout_comp_extent_get (3),
198 .BR llapi_layout_comp_extent_set (3),
199 .BR llapi_layout_comp_flags_get (3),
200 .BR llapi_layout_comp_flags_set (3),
201 .BR llapi_layout_comp_flags_clear (3),
202 .BR llapi_layout_comp_id_get (3),
203 .BR llapi_layout_comp_add (3),
204 .BR llapi_layout_comp_del (3),
205 .BR llapi_layout_comp_move (3),
206 .BR llapi_layout_comp_move_at (3),
207 .BR llapi_layout_file_comp_add (3),
208 .BR llapi_layout_file_comp_del (3),
210 .BR lfs-setstripe (1)