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