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 January 29, 2008
  30 .Dt EXTATTR 2
  31 .Os
  32 .Sh NAME
  33 .Nm extattr_get_fd ,
  34 .Nm extattr_set_fd ,
  35 .Nm extattr_delete_fd ,
  36 .Nm extattr_list_fd ,
  37 .Nm extattr_get_file ,
  38 .Nm extattr_set_file ,
  39 .Nm extattr_delete_file ,
  40 .Nm extattr_list_file ,
  41 .Nm extattr_get_link ,
  42 .Nm extattr_set_link ,
  43 .Nm extattr_delete_link ,
  44 .Nm extattr_list_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 ssize_t
  52 .Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
  53 .Ft ssize_t
  54 .Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  55 .Ft int
  56 .Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
  57 .Ft ssize_t
  58 .Fn extattr_list_fd "int fd" "int attrnamespace" "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_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  63 .Ft int
  64 .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
  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_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
  69 .Ft ssize_t
  70 .Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  71 .Ft int
  72 .Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
  73 .Ft ssize_t
  74 .Fn extattr_list_link "const char *path" "int attrnamespace" "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_set_fd ,
 139 .Fn extattr_delete_fd ,
 140 and
 141 .Fn extattr_list_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 CAVEAT
 171 This interface is under active development, and as such is subject to
 172 change as applications are adapted to use it.
 173 Developers are discouraged from relying on its stability.
 174 .Sh RETURN VALUES
 175 If successful, the
 176 .Fn extattr_get_file ,
 177 .Fn extattr_set_file ,
 178 and
 179 .Fn extattr_list_file
 180 calls return the number of bytes
 181 that were read or written from the
 182 .Fa data ,
 183 respectively, or if
 184 .Fa data
 185 was
 186 .Dv NULL ,
 187 then
 188 .Fn extattr_get_file
 189 and
 190 .Fn extattr_list_file
 191 return the number of bytes available to read.
 192 If any of the calls are unsuccessful, the value \-1 is returned
 193 and the global variable
 194 .Va errno
 195 is set to indicate the error.
 196 .Pp
 197 .Rv -std extattr_delete_file
 198 .Sh ERRORS
 199 The following errors may be returned by the system calls themselves.
 200 Additionally, the file system implementing the call may return any
 201 other errors it desires.
 202 .Bl -tag -width Er
 203 .It Bq Er EFAULT
 204 The
 205 .Fa attrnamespace
 206 and
 207 .Fa attrname
 208 arguments,
 209 or the memory range defined by
 210 .Fa data
 211 and
 212 .Fa nbytes
 213 point outside the process's allocated address space.
 214 .It Bq Er ENAMETOOLONG
 215 The attribute name was longer than
 216 .Dv EXTATTR_MAXNAMELEN .
 217 .El
 218 .Pp
 219 The
 220 .Fn extattr_get_fd ,
 221 .Fn extattr_set_fd ,
 222 .Fn extattr_delete_fd ,
 223 and
 224 .Fn extattr_list_fd
 225 system calls may also fail if:
 226 .Bl -tag -width Er
 227 .It Bq Er EBADF
 228 The file descriptor referenced by
 229 .Fa fd
 230 was invalid.
 231 .El
 232 .Pp
 233 Additionally, the
 234 .Fn extattr_get_file ,
 235 .Fn extattr_set_file ,
 236 and
 237 .Fn extattr_delete_file
 238 calls may also fail due to the following errors:
 239 .Bl -tag -width Er
 240 .It Bq Er ENOATTR
 241 The requested attribute was not defined for this file.
 242 .It Bq Er ENOTDIR
 243 A component of the path prefix is not a directory.
 244 .It Bq Er ENAMETOOLONG
 245 A component of a pathname exceeded 255 characters,
 246 or an entire path name exceeded 1023 characters.
 247 .It Bq Er ENOENT
 248 A component of the path name that must exist does not exist.
 249 .It Bq Er EACCES
 250 Search permission is denied for a component of the path prefix.
 251 .\" XXX are any missing?
 252 .El
 253 .Sh SEE ALSO
 254 .Xr extattr 3 ,
 255 .Xr getextattr 8 ,
 256 .Xr setextattr 8 ,
 257 .Xr extattr 9 ,
 258 .Xr VOP_GETEXTATTR 9 ,
 259 .Xr VOP_SETEXTATTR 9
 260 .Sh HISTORY
 261 Extended attribute support was developed as part of the
 262 .Tn TrustedBSD
 263 Project, and introduced in
 264 .Fx 5.0 .
 265 It was developed to support security extensions requiring additional labels
 266 to be associated with each file or directory.
 267 .Sh BUGS
 268 In earlier versions of this API, passing an empty string for the
 269 attribute name to
 270 .Fn extattr_get_fd ,
 271 .Fn extattr_get_file ,
 272 or
 273 .Fn extattr_get_link
 274 would return the list of attributes defined for the target object.
 275 This interface has been deprecated in preference to using the explicit
 276 list API, and should not be used.