1.\" $NetBSD: extattr_get_file.2,v 1.6 2014/11/11 08:10:02 njoly Exp $ 2.\" 3.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> 4.\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" FreeBSD: src/lib/libc/sys/extattr_get_file.2,v 1.14 2004/07/05 17:12:52 ru Exp 29.\" 30.Dd August 3, 2011 31.Dt EXTATTR_GET_FILE 2 32.Os 33.Sh NAME 34.Nm extattr_get_fd , 35.Nm extattr_set_fd , 36.Nm extattr_delete_fd , 37.Nm extattr_list_fd , 38.Nm extattr_get_file , 39.Nm extattr_set_file , 40.Nm extattr_delete_file , 41.Nm extattr_list_file , 42.Nm extattr_get_link , 43.Nm extattr_set_link , 44.Nm extattr_delete_link , 45.Nm extattr_list_link 46.Nd system calls to manipulate VFS extended attributes 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/extattr.h 52.Ft ssize_t 53.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" 54.Ft int 55.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" 56.Ft int 57.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname" 58.Ft ssize_t 59.Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes" 60.Ft ssize_t 61.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" 62.Ft int 63.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" 64.Ft int 65.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname" 66.Ft ssize_t 67.Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes" 68.Ft ssize_t 69.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" 70.Ft int 71.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" 72.Ft int 73.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname" 74.Ft ssize_t 75.Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes" 76.Sh DESCRIPTION 77Named extended attributes are meta-data associated with vnodes 78representing files and directories. 79They exist as 80.Qq Li name=value 81pairs within a set of namespaces. 82.Pp 83The 84.Fn extattr_get_file 85system call retrieves the value of the specified extended attribute into 86a buffer pointed to by 87.Fa data 88of size 89.Fa nbytes . 90The 91.Fn extattr_set_file 92system call sets the value of the specified extended attribute to the data 93described by 94.Fa data . 95The 96.Fn extattr_delete_file 97system call deletes the extended attribute specified. 98The 99.Fn extattr_list_file 100returns a list of attributes present in the requested namespace. 101Each list entry consists of a single byte containing the length 102of the attribute name, followed by the attribute name. 103The attribute name is not terminated by ASCII 0 (nul). 104The 105.Fn extattr_get_file 106and 107.Fn extattr_list_file 108calls consume the 109.Fa data 110and 111.Fa nbytes 112arguments in the style of 113.Xr read 2 ; 114.Fn extattr_set_file 115consumes these arguments in the style of 116.Xr write 2 . 117.Pp 118If 119.Fa data 120is 121.Dv NULL 122in a call to 123.Fn extattr_get_file 124then the size of defined extended attribute data will be returned, rather 125than the quantity read, permitting applications to test the size of the 126data without performing a read. 127.Pp 128The 129.Fn extattr_delete_link , 130.Fn extattr_get_link , 131and 132.Fn extattr_set_link 133system calls behave in the same way as their _file counterparts, except that 134they do not follow symlinks. 135.Pp 136The 137.Fn extattr_get_fd , 138.Fn extattr_set_fd , 139and 140.Fn extattr_delete_fd 141calls are identical to their 142.Qq Li _file 143counterparts except for the first argument. 144The 145.Qq Li _fd 146functions take a file descriptor, while the 147.Qq Li _file 148functions take a path. 149Both arguments describe a file associated with the extended attribute 150that should be manipulated. 151.Pp 152The following arguments are common to all the system calls described here: 153.Bl -tag -width attrnamespace 154.It Fa attrnamespace 155the namespace in which the extended attribute resides; see 156.Xr extattr 9 157.It Fa attrname 158the name of the extended attribute 159.El 160.Pp 161Named extended attribute semantics vary by file system implementing the call. 162Not all operations may be supported for a particular attribute. 163Additionally, the format of the data in 164.Fa data 165is attribute-specific. 166.Pp 167For more information on named extended attributes, please see 168.Xr extattr 9 . 169.Sh RETURN VALUES 170If successful, the 171.Fn extattr_get_file 172and 173.Fn extattr_set_file 174calls return the number of bytes 175that were read or written from the 176.Fa data , 177respectively, or if 178.Fa data 179was 180.Dv NULL , 181then 182.Fn extattr_get_file 183returns the number of bytes available to read. 184If any of the calls are unsuccessful, the value \-1 is returned 185and the global variable 186.Va errno 187is set to indicate the error. 188.Pp 189.Rv -std extattr_delete_file 190.Sh ERRORS 191The following errors may be returned by the system calls themselves. 192Additionally, the file system implementing the call may return any 193other errors it desires. 194.Bl -tag -width Er 195.It Bq Er EFAULT 196The 197.Fa attrnamespace 198and 199.Fa attrname 200arguments, 201or the memory range defined by 202.Fa data 203and 204.Fa nbytes 205point outside the process's allocated address space. 206.It Bq Er ENAMETOOLONG 207The attribute name was longer than 208.Dv EXTATTR_MAXNAMELEN . 209.El 210.Pp 211The 212.Fn extattr_get_fd , 213.Fn extattr_set_fd , 214and 215.Fn extattr_delete_fd 216system calls may also fail if: 217.Bl -tag -width Er 218.It Bq Er EBADF 219The file descriptor referenced by 220.Fa fd 221was invalid. 222.El 223.Pp 224Additionally, the 225.Fn extattr_get_file , 226.Fn extattr_set_file , 227and 228.Fn extattr_delete_file 229calls may also fail due to the following errors: 230.Bl -tag -width Er 231.It Bq Er EACCES 232Search permission is denied for a component of the path prefix. 233.It Bq Er ENAMETOOLONG 234A component of a pathname exceeded 235.Brq Dv NAME_MAX 236characters, 237or an entire path name exceeded 238.Brq Dv PATH_MAX 239characters. 240.It Bq Er ENOENT 241A component of the path name that must exist does not exist. 242.It Bq Er ENOTDIR 243A component of the path prefix is not a directory. 244.\" XXX are any missing? 245.El 246.Sh SEE ALSO 247.Xr getextattr 1 , 248.Xr extattr 3 , 249.Xr extattr 9 250.Sh HISTORY 251Extended attribute support was developed as part of the 252.Tn TrustedBSD 253Project, and introduced in 254.Fx 5.0 255and 256.Nx 3.0 . 257It was developed to support security extensions requiring additional labels 258to be associated with each file or directory. 259.Sh CAVEATS 260This interface is under active development, and as such is subject to 261change as applications are adapted to use it. 262Developers are discouraged from relying on its stability. 263.Pp 264Note that previous versions of this man page incorrectly stated that 265.Fn extattr_list_file 266returned a list of attribute names separated by ASCII 0 (nul). 267