lib/libc/sys/extattr.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: src/lib/libc/sys/extattr_get_file.2,v 1.19 2008/01/29 18:15:38 trhodes Exp $
  28 .\"
  29 .Dd May 8, 2010
  30 .Dt EXTATTR 2
  31 .Os
  32 .Sh NAME
  33 .Nm extattr_get_file ,
  34 .Nm extattr_set_file ,
  35 .Nm extattr_delete_file
  36 .Nd system calls to manipulate VFS extended attributes
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/extattr.h
  42 .Ft ssize_t
  43 .Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
  44 .Ft int
  45 .Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
  46 .Ft int
  47 .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
  48 .Sh DESCRIPTION
  49 Named extended attributes are meta-data associated with vnodes
  50 representing files and directories.
  51 They exist as
  52 .Qq Li name=value
  53 pairs within a set of namespaces.
  54 .Pp
  55 The
  56 .Fn extattr_get_file
  57 system call retrieves the value of the specified extended attribute into
  58 a buffer pointed to by
  59 .Fa data
  60 of size
  61 .Fa nbytes .
  62 The
  63 .Fn extattr_set_file
  64 system call sets the value of the specified extended attribute to the data
  65 described by
  66 .Fa data .
  67 The
  68 .Fn extattr_delete_file
  69 system call deletes the extended attribute specified.
  70 The
  71 .Fn extattr_get_file
  72 call consumes the
  73 .Fa data
  74 and
  75 .Fa nbytes
  76 arguments in the style of
  77 .Xr read 2 ;
  78 .Fn extattr_set_file
  79 consumes these arguments in the style of
  80 .Xr write 2 .
  81 .Pp
  82 If
  83 .Fa data
  84 is
  85 .Dv NULL
  86 in a call to
  87 .Fn extattr_get_file
  88 then the size of defined extended attribute data will be returned, rather
  89 than the quantity read, permitting applications to test the size of the
  90 data without performing a read.
  91 .Pp
  92 The following arguments are common to all the system calls described here:
  93 .Bl -tag -width attrnamespace
  94 .It Fa attrnamespace
  95 the namespace in which the extended attribute resides; see
  96 .Xr extattr 9
  97 .It Fa attrname
  98 the name of the extended attribute
  99 .El
 100 .Pp
 101 Named extended attribute semantics vary by file system implementing the call.
 102 Not all operations may be supported for a particular attribute.
 103 Additionally, the format of the data in
 104 .Fa data
 105 is attribute-specific.
 106 .Pp
 107 For more information on named extended attributes, please see
 108 .Xr extattr 9 .
 109 .Sh CAVEAT
 110 This interface is under active development, and as such is subject to
 111 change as applications are adapted to use it.
 112 Developers are discouraged from relying on its stability.
 113 .Sh RETURN VALUES
 114 If successful, the
 115 .Fn extattr_get_file
 116 and
 117 .Fn extattr_set_file
 118 calls return the number of bytes
 119 that were read or written from the
 120 .Fa data ,
 121 respectively, or if
 122 .Fa data
 123 was
 124 .Dv NULL ,
 125 then
 126 .Fn extattr_get_file
 127 returns the number of bytes available to read.
 128 If any of the calls are unsuccessful, the value \-1 is returned
 129 and the global variable
 130 .Va errno
 131 is set to indicate the error.
 132 .Pp
 133 .Rv -std extattr_delete_file
 134 .Sh ERRORS
 135 The following errors may be returned by the system calls themselves.
 136 Additionally, the file system implementing the call may return any
 137 other errors it desires.
 138 .Bl -tag -width Er
 139 .It Bq Er EFAULT
 140 The
 141 .Fa attrnamespace
 142 and
 143 .Fa attrname
 144 arguments,
 145 or the memory range defined by
 146 .Fa data
 147 and
 148 .Fa nbytes
 149 point outside the process's allocated address space.
 150 .It Bq Er ENAMETOOLONG
 151 The attribute name was longer than
 152 .Dv EXTATTR_MAXNAMELEN .
 153 .El
 154 .Pp
 155 Additionally, the
 156 .Fn extattr_get_file ,
 157 .Fn extattr_set_file ,
 158 and
 159 .Fn extattr_delete_file
 160 calls may also fail due to the following errors:
 161 .Bl -tag -width Er
 162 .It Bq Er ENOATTR
 163 The requested attribute was not defined for this file.
 164 .It Bq Er ENOTDIR
 165 A component of the path prefix is not a directory.
 166 .It Bq Er ENAMETOOLONG
 167 A component of a pathname exceeded 255 characters,
 168 or an entire path name exceeded 1023 characters.
 169 .It Bq Er ENOENT
 170 A component of the path name that must exist does not exist.
 171 .It Bq Er EACCES
 172 Search permission is denied for a component of the path prefix.
 173 .\" XXX are any missing?
 174 .El
 175 .Sh SEE ALSO
 176 .\".Xr extattr 3 ,
 177 .\".Xr getextattr 8 ,
 178 .\".Xr setextattr 8 ,
 179 .Xr extattr 9 ,
 180 .Xr VOP_GETEXTATTR 9 ,
 181 .Xr VOP_SETEXTATTR 9
 182 .Sh HISTORY
 183 Extended attribute support was developed as part of the
 184 .Tn TrustedBSD
 185 Project, and introduced in
 186 .Fx 5.0 .
 187 It was developed to support security extensions requiring additional labels
 188 to be associated with each file or directory.
 189 .Sh BUGS
 190 In earlier versions of this API, passing an empty string for the
 191 attribute name to
 192 .Fn extattr_get_file
 193 would return the list of attributes defined for the target object.
 194 This interface has been deprecated in preference to using the explicit
 195 list API, and should not be used.