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 The functions
  26 .BR llapi_layout_get_by_xattr() ,
  27 .BR llapi_layout_get_by_fd() ,
  28 .BR llapi_layout_get_by_fid() ,
  29 and
  30 .BR llapi_layout_get_by_path()
  31 return a pointer to a newly-allocated
  32 .B struct llapi_layout
  33 containing the layout information for the file referenced by
  34 .IR lov_xattr ,
  35 .IR fd ,
  36 .IR fid ,
  37 or
  38 .IR path ,
  39 respectively.  The
  40 .B struct llapi_layout
  41 is an opaque entity containing the layout information for a file in a
  42 Lustre filesystem.  Its internal structure should not be directly
  43 accessed by an application.  See
  44 .BR llapi_layout (7).
  45 The pointer should be freed with
  46 .B llapi_layout_free()
  47 when it is no longer needed.
  48 .PP
  49 For
  50 .BR llapi_layout_get_by_xattr() ,
  51 .I lov_xattr
  52 is a Lustre layout extended attribute (LOV EA) from a file or directory in
  53 a Lustre filesystem. The
  54 .I lov_xattr
  55 should be the raw xattr without being byte-swapped, since this function will
  56 swap it to the local machine endianness properly.
  57 .PP
  58 For
  59 .BR llapi_layout_get_by_fd() ,
  60 .I fd
  61 is a valid open file descriptor for a file or directory in a Lustre
  62 filesystem.
  63 .PP
  64 For
  65 .BR llapi_layout_get_by_fid() ,
  66 .I lustre_path
  67 identifies the Lustre filesystem containing the file represented by
  68 .IR fid .
  69 It is typically the filesystem root directory, 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 to control how a layout is retrieved.  Currently
  85 .B llapi_layout_get_by_fd()
  86 and
  87 .B llapi_layout_get_by_fid()
  88 do not accept any values for
  89 .IR flags ,
  90 while
  91 .B llapi_layout_get_by_path()
  92 accepts only one flag as follows:
  93 .TP 5
  94 .SM LLAPI_LAYOUT_GET_EXPECTED
  95 Unspecified attribute values are replaced by the literal default values
  96 that will be assigned when the file is created or first written to.
  97 A default value is inherited from the parent directory if the attribute
  98 is specified there, otherwise it is inherited from the filesystem root.
  99 This flag is only recognized by
 100 .BR llapi_layout_get_by_path() .
 101 Unspecified attributes may belong to directories and never-written-to
 102 files.
 103 .sp
 104 By default, layouts report the abstract value
 105 .B LLAPI_LAYOUT_DEFAULT
 106 to indicate an unspecified attribute.  Use
 107 .B LLAPI_LAYOUT_GET_EXPECTED
 108 to discover the expected literal values for new files in a given
 109 directory.  Do not use it if you need to distinguish between specified
 110 and unspecified attributes.  The flag has no effect if
 111 .I path
 112 names a file or directory with a fully specified layout.
 113 .sp
 114 For concreteness, consider a Lustre filesystem with a default stripe
 115 size of 1048576 and a default stripe count of 1.  A user sets the stripe
 116 count for directory D to 2 (thus overriding the filesystem-wide
 117 default) but leaves the stripe size unspecified.  Newly created files in
 118 D inherit a stripe count of 2 from D and a stripe size of 1048576 from
 119 the filesystem default.  The layout of D returned by
 120 .B llapi_layout_get_by_path(D, 0)
 121 has the abstract stripe size value
 122 .BR LLAPI_LAYOUT_DEFAULT ,
 123 since stripe size is unspecified, while
 124 .B llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED)
 125 reports the literal value 1048576.  Both forms report a stripe count
 126 of 2, since that attribute is specified.
 127 .PP
 128 Valid arguments for
 129 .I flags
 130 with
 131 .B llapi_layout_get_by_xattr()
 132 are:
 133 .TP 5
 134 .SM LLAPI_LAYOUT_GET_CHECK
 135 If the
 136 .B LLAPI_LAYOUT_GET_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 files, so it should not be passed if the xattr is a default
 140 layout from a directory.
 141 .TP
 142 .SM LLAPI_LAYOUT_GET_COPY
 143 If the
 144 .B LLAPI_LAYOUT_GET_COPY
 145 flag is set, this function will use a temporary buffer for byte swapping
 146 when necessary, leaving
 147 .I lov_xattr
 148 unmodified. Otherwise, the byte swapping will be done to the fields of the
 149 .I lov_xattr
 150 buffer directly.
 151 .SH NOTE
 152 When using these functions to copy an existing file's layout to create a
 153 new file with
 154 .B llapi_layout_file_open (3)
 155 for mirroring, migration, or as the template for a new file,
 156 .BR llapi_layout_ost_index_reset (3)
 157 should be called to reset the OST index values for each component, so that
 158 the file copy is not created on exactly the same OSTs as the original file.
 159 .SH RETURN VALUES
 160 These functions return a valid pointer on success or
 161 .B NULL
 162 on failure with
 163 .B errno
 164 set to an approporiate error code.
 165 .SH ERRORS
 166 .TP 15
 167 .SM ENOMEM
 168 Insufficient storage space is available.
 169 .TP
 170 .SM ENOTTY
 171 File does not reside on a Lustre filesystem.
 172 .TP
 173 .SM ENOENT
 174 .I path
 175 does not exist.
 176 .TP
 177 .SM EINVAL
 178 An invalid argument was specified.
 179 .TP
 180 .SM EINTR
 181 The kernel returned less than the expected amount of data.
 182 .SH "SEE ALSO"
 183 .BR llapi_layout_file_open (3),
 184 .BR llapi_layout_ost_index_reset (3),
 185 .BR llapi_path2fid (3),
 186 .BR llapi_layout (7),
 187 .BR lustreapi (7)