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 llapi_layout_t
  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. Refer
  20 to the Lustre Operations Manual for detailed descriptions of these
  21 attributes.  For each attribute, there exists a pair of functions with
  22 the suffixes
  23 .B _get
  24 and
  25 .B _set
  26 that are used to read and assign the attribute value in a given layout.
  27 .PP
  28 Using this interface to create a file might consist of the following steps.
  29 .IP \[bu]
  30 Allocate a layout with
  31 .BR llapi_layout_alloc (3).
  32 .IP \[bu]
  33 Assign attribute values using the
  34 .B llapi_layout_*_set (3)
  35 functions.
  36 .IP \[bu]
  37 Create the file using
  38 .BR llapi_layout_file_create (3).
  39 .IP \[bu]
  40 Free the layout memory using
  41 .BR llapi_layout_free (3).
  42 .PP
  43 Similarly, these steps might be used to read a file layout:
  44 .IP \[bu]
  45 Obtain the layout with
  46 .BR llapi_layout_get_by_path (3),
  47 .BR llapi_layout_get_by_fd (3),
  48 or
  49 .BR llapi_layout_get_by_fid (3).
  50 .IP \[bu]
  51 Read attribute values using the
  52 .B llapi_layout_*_get (3)
  53 functions.
  54 .IP \[bu]
  55 Free the layout memory using
  56 .BR llapi_layout_free (3).
  57 .PP
  58 Using this interface to create a file with composite layout consists of the
  59 following steps.
  60 .IP \[bu]
  61 Allocate first layout component with
  62 .BR llapi_layout_alloc (3).
  63 .IP \[bu]
  64 Assign attribute values using the
  65 .B llapi_layout_*_set (3)
  66 functions.
  67 .IP \[bu]
  68 Allocate second layout component with
  69 .BR llapi_layout_alloc (3).
  70 .IP \[bu]
  71 Add the second layout into the first one using
  72 .BR llapi_layout_comp_add (3).
  73 .IP \[bu]
  74 Assign attribute values to second layout using the
  75 .BR llapi_layout_*_set (3)
  76 functions.
  77 .IP \[bu]
  78 Repeat above two steps to add more components.
  79 .IP \[bu]
  80 Create the file using
  81 .BR llapi_layout_file_create (3).
  82 .IP \[bu]
  83 Free the layout memory using
  84 .BR llapi_layout_free (3).
  85 .SH "EXAMPLE"
  86 Example 1: Create file with specified layout, then query the layout attributes.
  87 .PP
  88 .nf
  89 {
  90         /* Allocate layout */
  91         layout = llapi_layout_alloc();
  92
  93         /* Set attributes of layout */
  94         llapi_layout_stripe_count_set(layout, count);
  95         llapi_layout_stripe_size_set(layout, size);
  96
  97         /* Create file with specified layout */
  98         fd = llapi_layout_file_create(path, 0, 0640, layout);
  99
 100         /* Free layout */
 101         llapi_layout_free(layout);
 102
 103         /* Retrieve layout from file */
 104         layout = llapi_layout_get_by_path(path, 0);
 105
 106         /* Get attributes of layout */
 107         llapi_layout_stripe_size_get(layout, &size),
 108         llapi_layout_stripe_count_get(layout, &count);
 109
 110         /* Free layout */
 111         llapi_layout_free(layout);
 112 }
 113 .fi
 114 .PP
 115 Example 2: Create file with composite layout.
 116 .PP
 117 .nf
 118 {
 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)
 124
 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);
 130
 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);
 137
 138         /* Create file with specified composite layout */
 139         fd = llapi_layout_file_create(path, 0, 0640, head);
 140
 141         /* Free layout */
 142         llapi_layout_free(head);
 143 }
 144 .fi
 145 .PP
 146 Example 3: Traverse components of a composite layout.
 147 .PP
 148 .nf
 149 {
 150         /* Retrieve composite layout from file */
 151         layout = llapi_layout_get_by_path(path, 0);
 152
 153         /* Move cursor to the first component */
 154         rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
 155
 156         /* Traverse all components */
 157         while (rc == 0) {
 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);
 162
 163                 /* Advance cursor */
 164                 rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
 165         };
 166
 167         /* Free layout */
 168         llapi_layout_free(layout);
 169 }
 170 .fi
 171
 172 .SH "BUGS"
 173 Setting the OST index number is only supported for stripe number 0.
 174
 175 The RAID pattern may only be set to 0.
 176 .SH "SEE ALSO"
 177 .BR open (2),
 178 .BR lustre (7),
 179 .BR lustreapi (7),
 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_use (3),
 206 .BR llapi_layout_comp_use_id (3),
 207 .BR llapi_layout_file_comp_add (3),
 208 .BR llapi_layout_file_comp_del (3),
 209 .BR lfs (1),
 210 .BR lfs-setstripe (1)