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