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