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