lustre/doc/llapi_layout_get_by_fd.3

   1 .TH llapi_layout_get_by_fd 3 "2013 Oct 31" "Lustre User API"
   2 .SH NAME
   3 llapi_layout_get_by_fd, llapi_layout_get_by_fid, llapi_layout_get_by_path, \-
   4 obtain the layout of a Lustre file
   5 .SH SYNOPSIS
   6 .nf
   7 .B #include <lustre/lustreapi.h>
   8 .PP
   9 .BI "struct llapi_layout *llapi_layout_get_by_fd(int " fd ,
  10 .BI "                                     enum llapi_layout_get_flags " flags );
  11 .PP
  12 .BI "struct llapi_layout *llapi_layout_get_by_fid(const char *"lustre_path ,
  13 .BI "                                     const struct lu_fid *"fid ,
  14 .BI "                                     enum llapi_layout_get_flags " flags );
  15 .PP
  16 .BI "struct llapi_layout *llapi_layout_get_by_path(const char *"path ,
  17 .BI "                                     enum llapi_layout_get_flags " flags );
  18 .PP
  19 .BI "struct llapi_layout *llapi_layout_get_by_xattr(void *"lov_xattr ,
  20 .BI "                                     ssize_t " lov_xattr_size ,
  21 .BI "                                     enum llapi_layout_get_flags " flags );
  22 .fi
  23 .SH DESCRIPTION
  24 .PP
  25 .BR llapi_layout_get_by_xattr() ,
  26 .BR llapi_layout_get_by_fd() ,
  27 .BR llapi_layout_get_by_fid() ,
  28 and
  29 .BR llapi_layout_get_by_path()
  30 return a pointer to a newly-allocated
  31 .B struct llapi_layout
  32 containing the layout information for the file referenced by
  33 .IR lov_xattr ,
  34 .IR fd ,
  35 .IR fid ,
  36 or
  37 .IR path .
  38 The
  39 .B struct llapi_layout
  40 is an opaque entity containing the layout information for a file in a
  41 Lustre filesystem.  Its internal structure should not be directly
  42 accessed by an application.  See
  43 .BR llapi_layout (7).
  44 The pointer should be freed with
  45 .B llapi_layout_free()
  46 when it is no longer needed.
  47 .PP
  48 For
  49 .BR llapi_layout_get_by_xattr() ,
  50 .I lov_xattr
  51 is a Lustre layout extended attribute (LOV EA) from a file or directory in
  52 a Lustre filesystem. The
  53 .I lov_xattr
  54 should be the raw xattr without being byte-swapped, since this function will
  55 swap it properly.
  56 .PP
  57 For
  58 .BR llapi_layout_get_by_fd() ,
  59 .I fd
  60 is a valid open file descriptor for a file or directory in a Lustre
  61 filesystem.
  62 .PP
  63 For
  64 .BR llapi_layout_get_by_fid() ,
  65 the
  66 .I lustre_path
  67 argument serves to identify the Lustre filesystem containing the file
  68 represented by
  69 .IR fid .
  70 It is typically the filesystem root, but may also be any path beneath
  71 the root.  Use the function
  72 .BR llapi_path2fid (3)
  73 to obtain a
  74 .B struct lu_fid
  75 associated with a given path.
  76 .PP
  77 The function
  78 .B llapi_layout_get_by_path()
  79 accepts a
  80 .I path
  81 argument that names a file or directory in a Lustre filesystem.
  82 .PP
  83 Zero or more flags may be bitwise-or'd together in
  84 .I flags
  85 or
  86 .I xattr_flags
  87 to control how a layout is retrieved.  Currently
  88 .B llapi_layout_get_by_path()
  89 accepts only one flag, while
  90 .B llapi_layout_get_by_fd()
  91 and
  92 .B llapi_layout_get_by_fid()
  93 do not use any flags. The list of flags that can be used in
  94 .I flags
  95 is as follows:
  96 .TP 5
  97 .SM LLAPI_LAYOUT_GET_EXPECTED
  98 Unspecified attribute values are replaced by the literal default values
  99 that will be assigned when the file is created or first written to.
 100 A default value is inherited from the parent directory if the attribute
 101 is specified there, otherwise it is inherited from the filesystem root.
 102 This flag is only recognized by
 103 .BR llapi_layout_get_by_path() .
 104 Unspecified attributes may belong to directories and never-written-to
 105 files.
 106 .sp
 107 By default, layouts report the abstract value
 108 .B LLAPI_LAYOUT_DEFAULT
 109 to indicate an unspecified attribute.  Use
 110 .B LLAPI_LAYOUT_GET_EXPECTED
 111 to discover the expected literal values for new files in a given
 112 directory.  Do not use it if you need to distinguish between specified
 113 and unspecified attributes.  The flag has no effect if
 114 .I path
 115 names a file or directory with a fully specified layout.
 116 .sp
 117 For concreteness, consider a Lustre filesystem with a default stripe
 118 size of 1048576 and a default stripe count of 1.  A user sets the stripe
 119 count for directory D to 2 (thus overriding the filesystem-wide
 120 default) but leaves the stripe size unspecified.  Newly created files in
 121 D inherit a stripe count of 2 from D and a stripe size of 1048576 from
 122 the filesystem default.  The layout of D returned by
 123 .B llapi_layout_get_by_path(D, 0)
 124 has the abstract stripe size value
 125 .BR LLAPI_LAYOUT_DEFAULT ,
 126 since stripe size is unspecified, while
 127 .B llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED)
 128 reports the literal value 1048576.  Both forms report a stripe count
 129 of 2, since that attribute is specified.
 130 .PP
 131 The values that can be used by
 132 .B llapi_layout_get_by_xattr()
 133 .I flags
 134 argument is as follows:
 135 .TP 5
 136 .SM LLAPI_LAYOUT_GET_CHECK
 137 If the
 138 .B LLAPI_LAYOUT_GET_CHECK
 139 flag is set, this function will check whether the objects count in lum
 140 is consistent with the stripe count in lum. This check only apply to
 141 regular files, so it should not be passed if the xattr is a default
 142 layout from a directory.
 143 .TP
 144 .SM LLAPI_LAYOUT_GET_COPY
 145 If the
 146 .B LLAPI_LAYOUT_GET_COPY
 147 flag is set, this function will use a temporary buffer for byte swapping
 148 when necessary, leaving
 149 .I lov_xattr
 150 unmodified. Otherwise, the byte swapping will be done to the fields of the
 151 .I lov_xattr
 152 buffer directly.
 153 .SH RETURN VALUES
 154 .LP
 155 .BR llapi_layout_get_by_fd() ,
 156 .BR llapi_layout_get_by_fid() ,
 157 and
 158 .B llapi_layout_get_by_path()
 159 return a valid pointer on success or
 160 .B NULL
 161 on failure with
 162 .B errno
 163 set to an approporiate error code.
 164 .SH ERRORS
 165 .TP 15
 166 .SM ENOMEM
 167 Insufficient storage space is available.
 168 .TP
 169 .SM ENOTTY
 170 File does not reside on a Lustre filesystem.
 171 .TP
 172 .SM ENOENT
 173 .I path
 174 does not exist.
 175 .TP
 176 .SM EINVAL
 177 An invalid argument was specified.
 178 .TP
 179 .SM EINTR
 180 The kernel returned less than the expected amount of data.
 181 .SH "SEE ALSO"
 182 .BR llapi_layout_file_open (3),
 183 .BR llapi_path2fid (3),
 184 .BR llapi_layout (7),
 185 .BR lustreapi (7)