lustre/doc/llapi_layout.7

   1 .TH llapi_layout 7 "2013 Oct 31" "Lustre User API"
   2 .SH NAME
   3 llapi_layout \- abstract interface to the layout of a Lustre file
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <lustre/lustreapi.h>
   7 .SH DESCRIPTION
   8 .LP
   9 The
  10 .B llapi_layout
  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.
  16 .PP
  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
  24 .B _get
  25 and
  26 .B _set
  27 that are used to read and assign the attribute value in a given layout.
  28 .PP
  29 Using this interface to create a file might consist of the following steps.
  30 .IP \[bu]
  31 Allocate
  32 .B struct layout
  33 with
  34 .BR llapi_layout_alloc (3).
  35 .IP \[bu]
  36 Assign attribute values using the
  37 .B llapi_layout_*_set (3)
  38 functions.
  39 .IP \[bu]
  40 Create the file using
  41 .BR llapi_layout_file_create (3).
  42 .IP \[bu]
  43 Free the layout memory using
  44 .BR llapi_layout_free (3).
  45 .PP
  46 Similarly, these steps might be used to read a file layout:
  47 .IP \[bu]
  48 One can allocate and initialize a new
  49 .B struct layout
  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),
  54 or
  55 .BR llapi_layout_get_by_xattr (3)
  56 functions.
  57 .IP \[bu]
  58 To access attribute values from
  59 .B struct llapi_layout
  60 use the
  61 .B llapi_layout_*_get (3)
  62 functions.
  63 .IP \[bu]
  64 To free the previously allocated layout memory use
  65 .BR llapi_layout_free (3).
  66 .PP
  67 Using this interface to create a file with composite layout consists of the
  68 following steps:
  69 .IP \[bu]
  70 Allocate first layout component with
  71 .BR llapi_layout_alloc (3).
  72 .IP \[bu]
  73 Assign attribute values using the
  74 .B llapi_layout_*_set (3)
  75 functions.
  76 .IP \[bu]
  77 Allocate second layout component with
  78 .BR llapi_layout_alloc (3).
  79 .IP \[bu]
  80 Add the second layout into the first one using
  81 .BR llapi_layout_comp_add (3).
  82 .IP \[bu]
  83 Assign attribute values to second layout using the
  84 .BR llapi_layout_*_set (3)
  85 functions.
  86 .IP \[bu]
  87 Repeat above two steps to add more components.
  88 .IP \[bu]
  89 Create the file using
  90 .BR llapi_layout_file_create (3).
  91 .IP \[bu]
  92 Free the layout memory using
  93 .BR llapi_layout_free (3).
  94 .SH "EXAMPLE"
  95 Example 1: Create file with specified layout, then query the layout attributes.
  96 .PP
  97 .nf
  98 {
  99         /* Allocate layout */
 100         struct llapi_layout *layout = llapi_layout_alloc();
 101
 102         /* Set attributes of layout */
 103         llapi_layout_stripe_count_set(layout, count);
 104         llapi_layout_stripe_size_set(layout, size);
 105
 106         /* Create file with specified layout */
 107         fd = llapi_layout_file_create(path, 0, 0640, layout);
 108
 109         /* Free layout */
 110         llapi_layout_free(layout);
 111
 112         /* Retrieve layout from file */
 113         layout = llapi_layout_get_by_path(path, 0);
 114
 115         /* Get attributes of layout */
 116         llapi_layout_stripe_size_get(layout, &size),
 117         llapi_layout_stripe_count_get(layout, &count);
 118
 119         /* Free layout */
 120         llapi_layout_free(layout);
 121 }
 122 .fi
 123 .PP
 124 Example 2: Create file with composite layout.
 125 .PP
 126 .nf
 127 {
 128         struct llapi_layout *head, *comp;
 129
 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)
 135
 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);
 141
 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);
 148
 149         /* Create file with specified composite layout */
 150         fd = llapi_layout_file_create(path, 0, 0640, head);
 151
 152         /* Free layout */
 153         llapi_layout_free(head);
 154 }
 155 .fi
 156 .PP
 157 Example 3: Traverse components of a composite layout.
 158 .PP
 159 .nf
 160 {
 161         /* Retrieve composite layout from file */
 162         layout = llapi_layout_get_by_path(path, 0);
 163
 164         /* Move cursor to the first component */
 165         rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
 166
 167         /* Traverse all components */
 168         while (rc == 0) {
 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);
 173
 174                 /* Advance cursor */
 175                 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
 176         };
 177
 178         /* Free layout */
 179         llapi_layout_free(layout);
 180 }
 181 .fi
 182
 183 .SH "BUGS"
 184 Setting the OST index number is only supported for stripe number 0.
 185
 186 The RAID pattern may only be set to 0.
 187 .SH "SEE ALSO"
 188 .BR open (2),
 189 .BR lustre (7),
 190 .BR lustreapi (7),
 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),
 221 .BR lfs (1),
 222 .BR lfs-setstripe (1)