lib/libc/sys/extattr_get_file.2

   1 .\"
   2 .\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
   3 .\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd October 11, 2021
  28 .Dt EXTATTR 2
  29 .Os
  30 .Sh NAME
  31 .Nm extattr_delete_fd ,
  32 .Nm extattr_delete_file ,
  33 .Nm extattr_delete_link ,
  34 .Nm extattr_get_fd ,
  35 .Nm extattr_get_file ,
  36 .Nm extattr_get_link ,
  37 .Nm extattr_list_fd ,
  38 .Nm extattr_list_file ,
  39 .Nm extattr_list_link ,
  40 .Nm extattr_set_fd ,
  41 .Nm extattr_set_file ,
  42 .Nm extattr_set_link
  43 .Nd system calls to manipulate VFS extended attributes
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In sys/types.h
  48 .In sys/extattr.h
  49 .Ft int
  50 .Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
  51 .Ft int
  52 .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
  53 .Ft int
  54 .Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
  55 .Ft ssize_t
  56 .Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
  57 .Ft ssize_t
  58 .Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
  59 .Ft ssize_t
  60 .Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
  61 .Ft ssize_t
  62 .Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes"
  63 .Ft ssize_t
  64 .Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
  65 .Ft ssize_t
  66 .Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
  67 .Ft ssize_t
  68 .Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  69 .Ft ssize_t
  70 .Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  71 .Ft ssize_t
  72 .Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  73 .Sh DESCRIPTION
  74 Named extended attributes are meta-data associated with vnodes
  75 representing files and directories.
  76 They exist as
  77 .Qq Li name=value
  78 pairs within a set of namespaces.
  79 .Pp
  80 The
  81 .Fn extattr_get_file
  82 system call retrieves the value of the specified extended attribute into
  83 a buffer pointed to by
  84 .Fa data
  85 of size
  86 .Fa nbytes .
  87 The
  88 .Fn extattr_set_file
  89 system call sets the value of the specified extended attribute to the data
  90 described by
  91 .Fa data .
  92 The
  93 .Fn extattr_delete_file
  94 system call deletes the extended attribute specified.
  95 The
  96 .Fn extattr_list_file
  97 returns a list of attributes present in the requested namespace.
  98 Each list entry consists of a single byte containing the length
  99 of the attribute name, followed by the attribute name.
 100 The attribute name is not terminated by ASCII 0 (nul).
 101 The
 102 .Fn extattr_get_file
 103 and
 104 .Fn extattr_list_file
 105 calls consume the
 106 .Fa data
 107 and
 108 .Fa nbytes
 109 arguments in the style of
 110 .Xr read 2 ;
 111 .Fn extattr_set_file
 112 consumes these arguments in the style of
 113 .Xr write 2 .
 114 .Pp
 115 If
 116 .Fa data
 117 is
 118 .Dv NULL
 119 in a call to
 120 .Fn extattr_get_file
 121 and
 122 .Fn extattr_list_file
 123 then the size of defined extended attribute data will be returned, rather
 124 than the quantity read, permitting applications to test the size of the
 125 data without performing a read.
 126 The
 127 .Fn extattr_delete_link ,
 128 .Fn extattr_get_link ,
 129 and
 130 .Fn extattr_set_link
 131 system calls behave in the same way as their _file counterparts, except that
 132 they do not follow symlinks.
 133 .Pp
 134 The
 135 .Fn extattr_get_fd ,
 136 .Fn extattr_delete_fd ,
 137 .Fn extattr_list_fd ,
 138 and
 139 .Fn extattr_set_fd
 140 calls are identical to their
 141 .Qq Li _file
 142 counterparts except for the first argument.
 143 The
 144 .Qq Li _fd
 145 functions take a file descriptor, while the
 146 .Qq Li _file
 147 functions take a path.
 148 Both arguments describe a file associated with the extended attribute
 149 that should be manipulated.
 150 The
 151 .Qq Li _fd
 152 functions can be used with file descriptors opened with the
 153 .Dv O_PATH
 154 flag.
 155 .Pp
 156 The following arguments are common to all the system calls described here:
 157 .Bl -tag -width attrnamespace
 158 .It Fa attrnamespace
 159 the namespace in which the extended attribute resides; see
 160 .Xr extattr 9
 161 .It Fa attrname
 162 the name of the extended attribute
 163 .El
 164 .Pp
 165 Named extended attribute semantics vary by file system implementing the call.
 166 Not all operations may be supported for a particular attribute.
 167 Additionally, the format of the data in
 168 .Fa data
 169 is attribute-specific.
 170 .Pp
 171 For more information on named extended attributes, please see
 172 .Xr extattr 9 .
 173 .Sh RETURN VALUES
 174 If successful, the
 175 .Fn extattr_get_fd ,
 176 .Fn extattr_get_file ,
 177 .Fn extattr_get_link ,
 178 .Fn extattr_list_fd ,
 179 .Fn extattr_list_file ,
 180 .Fn extattr_list_link ,
 181 .Fn extattr_set_fd ,
 182 .Fn extattr_set_file ,
 183 and
 184 .Fn extattr_set_link
 185 calls return the number of bytes
 186 that were read or written from the
 187 .Fa data ,
 188 respectively.
 189 If
 190 .Fa data
 191 was
 192 .Dv NULL ,
 193 then
 194 .Fn extattr_get_fd ,
 195 .Fn extattr_get_file ,
 196 .Fn extattr_get_link ,
 197 .Fn extattr_list_fd ,
 198 .Fn extattr_list_file ,
 199 and
 200 .Fn extattr_list_link
 201 return the number of bytes available to read.
 202 If any of the calls are unsuccessful, the value \-1 is returned
 203 and the global variable
 204 .Va errno
 205 is set to indicate the error.
 206 .Pp
 207 .Rv -std extattr_delete_file
 208 .Sh ERRORS
 209 The following errors may be returned by the system calls themselves.
 210 Additionally, the file system implementing the call may return any
 211 other errors it desires.
 212 .Bl -tag -width Er
 213 .It Bq Er EFAULT
 214 The
 215 .Fa attrnamespace
 216 and
 217 .Fa attrname
 218 arguments,
 219 or the memory range defined by
 220 .Fa data
 221 and
 222 .Fa nbytes
 223 point outside the process's allocated address space.
 224 .It Bq Er ENAMETOOLONG
 225 The attribute name was longer than
 226 .Dv EXTATTR_MAXNAMELEN .
 227 .El
 228 .Pp
 229 The
 230 .Fn extattr_get_fd ,
 231 .Fn extattr_set_fd ,
 232 .Fn extattr_delete_fd ,
 233 and
 234 .Fn extattr_list_fd
 235 system calls may also fail if:
 236 .Bl -tag -width Er
 237 .It Bq Er EBADF
 238 The file descriptor referenced by
 239 .Fa fd
 240 was invalid.
 241 .El
 242 .Pp
 243 Additionally, the
 244 .Fn extattr_get_file ,
 245 .Fn extattr_set_file ,
 246 and
 247 .Fn extattr_delete_file
 248 calls may also fail due to the following errors:
 249 .Bl -tag -width Er
 250 .It Bq Er ENOATTR
 251 The requested attribute was not defined for this file.
 252 .It Bq Er ENOTDIR
 253 A component of the path prefix is not a directory.
 254 .It Bq Er ENAMETOOLONG
 255 A component of a pathname exceeded 255 characters,
 256 or an entire path name exceeded 1023 characters.
 257 .It Bq Er ENOENT
 258 A component of the path name that must exist does not exist.
 259 .It Bq Er EACCES
 260 Search permission is denied for a component of the path prefix.
 261 .\" XXX are any missing?
 262 .El
 263 .Sh SEE ALSO
 264 .Xr extattr 3 ,
 265 .Xr getextattr 8 ,
 266 .Xr setextattr 8 ,
 267 .Xr extattr 9 ,
 268 .Xr VOP_GETEXTATTR 9 ,
 269 .Xr VOP_SETEXTATTR 9
 270 .Sh HISTORY
 271 Extended attribute support was developed as part of the
 272 .Tn TrustedBSD
 273 Project, and introduced in
 274 .Fx 5.0 .
 275 It was developed to support security extensions requiring additional labels
 276 to be associated with each file or directory.
 277 .Sh CAVEATS
 278 This interface is under active development, and as such is subject to
 279 change as applications are adapted to use it.
 280 Developers are discouraged from relying on its stability.
 281 .Sh BUGS
 282 In earlier versions of this API, passing an empty string for the
 283 attribute name to
 284 .Fn extattr_get_fd ,
 285 .Fn extattr_get_file ,
 286 or
 287 .Fn extattr_get_link
 288 would return the list of attributes defined for the target object.
 289 This interface has been deprecated in preference to using the explicit
 290 list API, and should not be used.