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 December 7, 2020
  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 .Pp
 153 The following arguments are common to all the system calls described here:
 154 .Bl -tag -width attrnamespace
 155 .It Fa attrnamespace
 156 the namespace in which the extended attribute resides; see
 157 .Xr extattr 9
 158 .It Fa attrname
 159 the name of the extended attribute
 160 .El
 161 .Pp
 162 Named extended attribute semantics vary by file system implementing the call.
 163 Not all operations may be supported for a particular attribute.
 164 Additionally, the format of the data in
 165 .Fa data
 166 is attribute-specific.
 167 .Pp
 168 For more information on named extended attributes, please see
 169 .Xr extattr 9 .
 170 .Sh RETURN VALUES
 171 If successful, the
 172 .Fn extattr_get_fd ,
 173 .Fn extattr_get_file ,
 174 .Fn extattr_get_link ,
 175 .Fn extattr_list_fd ,
 176 .Fn extattr_list_file ,
 177 .Fn extattr_list_link ,
 178 .Fn extattr_set_fd ,
 179 .Fn extattr_set_file ,
 180 and
 181 .Fn extattr_set_link
 182 calls return the number of bytes
 183 that were read or written from the
 184 .Fa data ,
 185 respectively.
 186 If
 187 .Fa data
 188 was
 189 .Dv NULL ,
 190 then
 191 .Fn extattr_get_fd ,
 192 .Fn extattr_get_file ,
 193 .Fn extattr_get_link ,
 194 .Fn extattr_list_fd ,
 195 .Fn extattr_list_file ,
 196 and
 197 .Fn extattr_list_link
 198 return the number of bytes available to read.
 199 If any of the calls are unsuccessful, the value \-1 is returned
 200 and the global variable
 201 .Va errno
 202 is set to indicate the error.
 203 .Pp
 204 .Rv -std extattr_delete_file
 205 .Sh ERRORS
 206 The following errors may be returned by the system calls themselves.
 207 Additionally, the file system implementing the call may return any
 208 other errors it desires.
 209 .Bl -tag -width Er
 210 .It Bq Er EFAULT
 211 The
 212 .Fa attrnamespace
 213 and
 214 .Fa attrname
 215 arguments,
 216 or the memory range defined by
 217 .Fa data
 218 and
 219 .Fa nbytes
 220 point outside the process's allocated address space.
 221 .It Bq Er ENAMETOOLONG
 222 The attribute name was longer than
 223 .Dv EXTATTR_MAXNAMELEN .
 224 .El
 225 .Pp
 226 The
 227 .Fn extattr_get_fd ,
 228 .Fn extattr_set_fd ,
 229 .Fn extattr_delete_fd ,
 230 and
 231 .Fn extattr_list_fd
 232 system calls may also fail if:
 233 .Bl -tag -width Er
 234 .It Bq Er EBADF
 235 The file descriptor referenced by
 236 .Fa fd
 237 was invalid.
 238 .El
 239 .Pp
 240 Additionally, the
 241 .Fn extattr_get_file ,
 242 .Fn extattr_set_file ,
 243 and
 244 .Fn extattr_delete_file
 245 calls may also fail due to the following errors:
 246 .Bl -tag -width Er
 247 .It Bq Er ENOATTR
 248 The requested attribute was not defined for this file.
 249 .It Bq Er ENOTDIR
 250 A component of the path prefix is not a directory.
 251 .It Bq Er ENAMETOOLONG
 252 A component of a pathname exceeded 255 characters,
 253 or an entire path name exceeded 1023 characters.
 254 .It Bq Er ENOENT
 255 A component of the path name that must exist does not exist.
 256 .It Bq Er EACCES
 257 Search permission is denied for a component of the path prefix.
 258 .\" XXX are any missing?
 259 .El
 260 .Sh SEE ALSO
 261 .Xr extattr 3 ,
 262 .Xr getextattr 8 ,
 263 .Xr setextattr 8 ,
 264 .Xr extattr 9 ,
 265 .Xr VOP_GETEXTATTR 9 ,
 266 .Xr VOP_SETEXTATTR 9
 267 .Sh HISTORY
 268 Extended attribute support was developed as part of the
 269 .Tn TrustedBSD
 270 Project, and introduced in
 271 .Fx 5.0 .
 272 It was developed to support security extensions requiring additional labels
 273 to be associated with each file or directory.
 274 .Sh CAVEATS
 275 This interface is under active development, and as such is subject to
 276 change as applications are adapted to use it.
 277 Developers are discouraged from relying on its stability.
 278 .Sh BUGS
 279 In earlier versions of this API, passing an empty string for the
 280 attribute name to
 281 .Fn extattr_get_fd ,
 282 .Fn extattr_get_file ,
 283 or
 284 .Fn extattr_get_link
 285 would return the list of attributes defined for the target object.
 286 This interface has been deprecated in preference to using the explicit
 287 list API, and should not be used.