lustre/doc/llapi_get_lum_file_fd.3

   1 .TH llapi_get_lum_file_fd 3 "2019 July 15" "Lustre User API"
   2 .SH NAME
   3 llapi_get_lum_file_fd, llapi_get_lum_dir_fd, llapi_get_lum_file,
   4 llapi_get_lum_dir \- get valid file attrbutes and LOV stripe information to
   5 the user.
   6
   7 .SH SYNOPSIS
   8 .nf
   9 .B #include <lustre/lustreapi.h>
  10 .PP
  11 .BI "int llapi_get_lum_file_fd(int " dir_fd ", const char *" fname ",
  12 .BI "                          __u64 *" valid ", lstatx_t *" statx ",
  13 .BI "                          struct lov_user_md *" lum ",
  14 .BI "                          size_t " lumsize ");"
  15 .PP
  16 .BI "int llapi_get_lum_dir_fd(int " dir_fd ", __u64 *" valid ",
  17 .BI "                        lstatx_t *" statx ", struct lov_user_md *" lum ",
  18 .BI "                        size_t " lumsize ");"
  19 .PP
  20 .BI "int llapi_get_lum_file(const char *" path ", __u64 *" valid ",
  21 .BI "                       lstatx_t *" statx ", struct lov_user_md *" lum ",
  22 .BI "                       size_t " lumsize ");"
  23 .PP
  24 .BI "int llapi_get_lum_dir(const char *" path ", __u64 *" valid ",
  25 .BI "                      lstatx_t *" statx ", struct lov_user_md *" lum ",
  26 .BI "                      size_t " lumsize ");"
  27 .fi
  28 .SH DESCRIPTION
  29 .PP
  30 The function
  31 .BR llapi_get_lum_file_fd() ,
  32 .BR llapi_get_lum_dir_fd() ,
  33 .BR llapi_get_lum_file() ,
  34 and
  35 .BR llapi_get_lum_dir()
  36 returns file attributes and LOV stripe information by an ioctl on the dir.
  37 .BR dir_fd
  38 is a file descriptor that refers to a directory. For function
  39 .BR llapi_get_lum_file_fd() ,
  40 if
  41 .BR fname
  42 is provided, it is a relative pathname that is interpreted relative to the
  43 directory referred to by
  44 .BR dir_fd .
  45
  46 The function
  47 .BR llapi_get_lum_dir_fd() ,
  48 .BR llapi_get_lum_file() ,
  49 and
  50 .BR llapi_get_lum_dir()
  51 can be used for applications that are only processing a single file or directory
  52 referred to by
  53 .BR dir_fd
  54 or
  55 .BR path .
  56
  57 The function
  58 .BR llapi_get_lum_file_fd()
  59 can be used for applications that process lots of files. It avoids opening,
  60 locking, and closing each file on the client if that is not needed. Multiple
  61 calls of this llapi can be done on the parent dir referenced by
  62 .B dir_fd
  63 with a single open for all files in that directory, and it also does not
  64 pollute the client dcache with millions of dentries when traversing a large
  65 filesystem.
  66
  67 The stripe information for the target file is returned to the user in the
  68 .B struct lov_user_md
  69 pointed to by
  70 .BR lum
  71 if it is not a NULL pointer. The file attribute information for the target file
  72 is returned in the
  73 .BR lstatx_t
  74 structure pointed to by
  75 .BR statx
  76 if it is not a NULL pointer.
  77 The output argument
  78 .BR valid
  79 contains the flags to indicate which fields in the returned file attributes
  80 have been valid filled in.
  81
  82 The valid flags are as follows:
  83 .TP
  84 OBD_MD_FLSIZE
  85 The returned file size is known strictly correct.
  86 .TP
  87 OBD_MD_FLBLOCKS
  88 The returned file blocks is known strictly correct.
  89 .TP
  90 OBD_MD_FLLAZYSIZE
  91 The returned file size is approximate, may never have been strictly correct.
  92 .TP
  93 OBD_MD_FLLAZYBLOCKS
  94 The returned file blocks is approximate, may never have been strictly correct.
  95 .TP
  96 OBD_MD_FLID
  97 The returned object ID is valid.
  98 .TP
  99 OBD_MD_FLATIME
 100 The returned access time is valid.
 101 .TP
 102 OBD_MD_FLMTIME
 103 The returned data modification time is valid.
 104 .TP
 105 OBD_MD_FLCTIME
 106 The returned change time is valid.
 107 .TP
 108 OBD_MD_FLBLKSZ
 109 The returned block size is valid.
 110 .TP
 111 OBD_MD_FLMODE
 112 The returned access bits (mode & ~S_IFMT) is valid.
 113 .TP
 114 OBD_MD_FLTYPE
 115 The returned object type (mode & S_IFMT) is valid.
 116 .TP
 117 OBD_MD_FLUID
 118 The returned user ID is vaild.
 119 .TP
 120 OBD_MD_FLGID
 121 The returned group ID is valid.
 122 .TP
 123 OBD_MD_FLFLAGS
 124 The returned flags word is valid.
 125 .TP
 126 OBD_MD_FLNLINK
 127 The returned link count is valid.
 128 .TP
 129 OBD_MD_FLRDEV
 130 The returned device number is valid.
 131 .SH RETURN VALUES
 132 .LP
 133 .BR llapi_get_lum_file_fd() ,
 134 .BR llapi_get_lum_dir_fd() ,
 135 .BR llapi_get_lum_file() ,
 136 and
 137 .BR llapi_get_lum_dir()
 138 return 0 on success or a negative errno value on failure.
 139 .SH ERRORS
 140 .TP 15
 141 .SM -ENOMEM
 142 Insufficient memory to complete operation.
 143 .TP
 144 .SM -EFAULT
 145 Memory region is not properly mapped.
 146 .TP
 147 .SM -EINVAL
 148 One or more invalid arguments are given.
 149 .TP
 150 .SM -EOPNOTSUPP
 151 The operation is not supported.
 152 .TP
 153 .SM -ENOTTY
 154 File does not reside on a Lustre filesystem.
 155 .TP
 156 .SM -ENOENT
 157 .I path
 158 does not exist.
 159 .TP
 160 .SM -EBADF
 161 .I dir_fd
 162 is not a valid open file descriptor.
 163 .SH "SEE ALSO"
 164 .BR lustreapi (7)