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() .
  32 .IP \[bu]
  33 Assign attribute values using the
  34 .B llapi_layout_*_set()
  35 functions.
  36 .IP \[bu]
  37 Create the file using
  38 .BR llapi_layout_file_create() .
  39 .IP \[bu]
  40 Free the layout memory using
  41 .BR llapi_layout_free() .
  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() ,
  47 .BR llapi_layout_get_by_fd() ,
  48 or
  49 .BR llapi_layout_get_by_fid() .
  50 .IP \[bu]
  51 Read attribute values using the
  52 .B llapi_layout_*_get()
  53 functions.
  54 .IP \[bu]
  55 Free the layout memory using
  56 .BR llapi_layout_free() .
  57 .SH "EXAMPLE"
  58 .nf
  59 #include <errno.h>
  60 #include <string.h>
  61 #include <stdint.h>
  62 #include <unistd.h>
  63 #include <stdio.h>
  64 #include <lustre/lustreapi.h>
  65
  66 int main(int argc, char *argv[])
  67 {
  68         int             fd;
  69         struct llapi_layout *layout;
  70         uint64_t        count = 2;
  71         uint64_t        size = 1048576;
  72         char            *path;
  73
  74         if (argc != 2)
  75                 return -1;
  76
  77         path = argv[1];
  78         layout = llapi_layout_alloc();
  79         llapi_layout_stripe_count_set(layout, count);
  80         llapi_layout_stripe_size_set(layout, size);
  81         fd = llapi_layout_file_create(path, 0, 0640, layout);
  82         if (fd < 0) {
  83                 fprintf(stderr, "cannot create %s: %s\\n", path,
  84                         strerror(errno));
  85                 return -1;
  86         }
  87         close(fd);
  88         llapi_layout_free(layout);
  89
  90         layout = llapi_layout_get_by_path(path, 0);
  91         llapi_layout_stripe_size_get(layout, &size),
  92         llapi_layout_stripe_count_get(layout, &count);
  93         printf("%s with stripe size %llu, striped across %llu OSTs,"
  94                " has been created!\\n", path, size, count);
  95         llapi_layout_free(layout);
  96         return 0;
  97 }
  98 .fi
  99 .SH "BUGS"
 100 Setting the OST index number is only supported for stripe number 0.
 101
 102 The RAID pattern may only be set to 0.
 103 .SH "SEE ALSO"
 104 .BR open (2),
 105 .BR lustre (7),
 106 .BR lustreapi (7),
 107 .BR llapi_layout_alloc (3),
 108 .BR llapi_layout_file_create (3),
 109 .BR llapi_layout_file_open (3),
 110 .BR llapi_layout_free (3),
 111 .BR llapi_layout_get_by_fd (3),
 112 .BR llapi_layout_get_by_fid (3),
 113 .BR llapi_layout_get_by_path (3),
 114 .BR llapi_layout_ost_index_get (3),
 115 .BR llapi_layout_ost_index_set (3),
 116 .BR llapi_layout_pattern_get (3),
 117 .BR llapi_layout_pattern_set (3),
 118 .BR llapi_layout_pool_name_get (3),
 119 .BR llapi_layout_pool_name_set (3),
 120 .BR llapi_layout_stripe_count_get (3),
 121 .BR llapi_layout_stripe_count_set (3),
 122 .BR llapi_layout_stripe_size_get (3),
 123 .BR llapi_layout_stripe_size_set (3),
 124 .BR lfs (1)