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 or
  54 .BR llapi_layout_get_by_fid (3)
  55 functions.
  56 .IP \[bu]
  57 To access attribute values from
  58 .B struct llapi_layout
  59 use the
  60 .B llapi_layout_*_get (3)
  61 functions.
  62 .IP \[bu]
  63 To free the previously allocated layout memory use
  64 .BR llapi_layout_free (3).
  65 .PP
  66 Using this interface to create a file with composite layout consists of the
  67 following steps:
  68 .IP \[bu]
  69 Allocate first layout component with
  70 .BR llapi_layout_alloc (3).
  71 .IP \[bu]
  72 Assign attribute values using the
  73 .B llapi_layout_*_set (3)
  74 functions.
  75 .IP \[bu]
  76 Allocate second layout component with
  77 .BR llapi_layout_alloc (3).
  78 .IP \[bu]
  79 Add the second layout into the first one using
  80 .BR llapi_layout_comp_add (3).
  81 .IP \[bu]
  82 Assign attribute values to second layout using the
  83 .BR llapi_layout_*_set (3)
  84 functions.
  85 .IP \[bu]
  86 Repeat above two steps to add more components.
  87 .IP \[bu]
  88 Create the file using
  89 .BR llapi_layout_file_create (3).
  90 .IP \[bu]
  91 Free the layout memory using
  92 .BR llapi_layout_free (3).
  93 .SH "EXAMPLE"
  94 Example 1: Create file with specified layout, then query the layout attributes.
  95 .PP
  96 .nf
  97 {
  98         /* Allocate layout */
  99         struct llapi_layout *layout = llapi_layout_alloc();
 100
 101         /* Set attributes of layout */
 102         llapi_layout_stripe_count_set(layout, count);
 103         llapi_layout_stripe_size_set(layout, size);
 104
 105         /* Create file with specified layout */
 106         fd = llapi_layout_file_create(path, 0, 0640, layout);
 107
 108         /* Free layout */
 109         llapi_layout_free(layout);
 110
 111         /* Retrieve layout from file */
 112         layout = llapi_layout_get_by_path(path, 0);
 113
 114         /* Get attributes of layout */
 115         llapi_layout_stripe_size_get(layout, &size),
 116         llapi_layout_stripe_count_get(layout, &count);
 117
 118         /* Free layout */
 119         llapi_layout_free(layout);
 120 }
 121 .fi
 122 .PP
 123 Example 2: Create file with composite layout.
 124 .PP
 125 .nf
 126 {
 127         struct llapi_layout *head, *comp;
 128
 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)
 134
 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);
 140
 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);
 147
 148         /* Create file with specified composite layout */
 149         fd = llapi_layout_file_create(path, 0, 0640, head);
 150
 151         /* Free layout */
 152         llapi_layout_free(head);
 153 }
 154 .fi
 155 .PP
 156 Example 3: Traverse components of a composite layout.
 157 .PP
 158 .nf
 159 {
 160         /* Retrieve composite layout from file */
 161         layout = llapi_layout_get_by_path(path, 0);
 162
 163         /* Move cursor to the first component */
 164         rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
 165
 166         /* Traverse all components */
 167         while (rc == 0) {
 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);
 172
 173                 /* Advance cursor */
 174                 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
 175         };
 176
 177         /* Free layout */
 178         llapi_layout_free(layout);
 179 }
 180 .fi
 181
 182 .SH "BUGS"
 183 Setting the OST index number is only supported for stripe number 0.
 184
 185 The RAID pattern may only be set to 0.
 186 .SH "SEE ALSO"
 187 .BR open (2),
 188 .BR lustre (7),
 189 .BR lustreapi (7),
 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),
 219 .BR lfs (1),
 220 .BR lfs-setstripe (1)