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