1.\" $NetBSD: extattr_get_file.2,v 1.3 2005/01/02 18:28:48 wiz 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 January 2, 2004 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, separated 101by ASCII 0 (nul) characters. 102The 103.Fn extattr_get_file 104and 105.Fn extattr_list_file 106calls consume the 107.Fa data 108and 109.Fa nbytes 110arguments in the style of 111.Xr read 2 ; 112.Fn extattr_set_file 113consumes these arguments in the style of 114.Xr write 2 . 115.Pp 116If 117.Fa data 118is 119.Dv NULL 120in a call to 121.Fn extattr_get_file 122then the size of defined extended attribute data will be returned, rather 123than the quantity read, permitting applications to test the size of the 124data without performing a read. 125.Pp 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_set_fd , 137and 138.Fn extattr_delete_fd 139calls are identical to their 140.Qq Li _file 141counterparts except for the first argument. 142The 143.Qq Li _fd 144functions take a file descriptor, while the 145.Qq Li _file 146functions take a path. 147Both arguments describe a file associated with the extended attribute 148that should be manipulated. 149.Pp 150The following arguments are common to all the system calls described here: 151.Bl -tag -width attrnamespace 152.It Fa attrnamespace 153the namespace in which the extended attribute resides; see 154.Xr extattr 9 155.It Fa attrname 156the name of the extended attribute 157.El 158.Pp 159Named extended attribute semantics vary by file system implementing the call. 160Not all operations may be supported for a particular attribute. 161Additionally, the format of the data in 162.Fa data 163is attribute-specific. 164.Pp 165For more information on named extended attributes, please see 166.Xr extattr 9 . 167.Sh RETURN VALUES 168If successful, the 169.Fn extattr_get_file 170and 171.Fn extattr_set_file 172calls return the number of bytes 173that were read or written from the 174.Fa data , 175respectively, or if 176.Fa data 177was 178.Dv NULL , 179then 180.Fn extattr_get_file 181returns the number of bytes available to read. 182If any of the calls are unsuccessful, the value \-1 is returned 183and the global variable 184.Va errno 185is set to indicate the error. 186.Pp 187.Rv -std extattr_delete_file 188.Sh ERRORS 189The following errors may be returned by the system calls themselves. 190Additionally, the file system implementing the call may return any 191other errors it desires. 192.Bl -tag -width Er 193.It Bq Er EFAULT 194The 195.Fa attrnamespace 196and 197.Fa attrname 198arguments, 199or the memory range defined by 200.Fa data 201and 202.Fa nbytes 203point outside the process's allocated address space. 204.It Bq Er ENAMETOOLONG 205The attribute name was longer than 206.Dv EXTATTR_MAXNAMELEN . 207.El 208.Pp 209The 210.Fn extattr_get_fd , 211.Fn extattr_set_fd , 212and 213.Fn extattr_delete_fd 214system calls may also fail if: 215.Bl -tag -width Er 216.It Bq Er EBADF 217The file descriptor referenced by 218.Fa fd 219was invalid. 220.El 221.Pp 222Additionally, the 223.Fn extattr_get_file , 224.Fn extattr_set_file , 225and 226.Fn extattr_delete_file 227calls may also fail due to the following errors: 228.Bl -tag -width Er 229.It Bq Er ENOTDIR 230A component of the path prefix is not a directory. 231.It Bq Er ENAMETOOLONG 232A component of a pathname exceeded 255 characters, 233or an entire path name exceeded 1023 characters. 234.It Bq Er ENOENT 235A component of the path name that must exist does not exist. 236.It Bq Er EACCES 237Search permission is denied for a component of the path prefix. 238.\" XXX are any missing? 239.El 240.Sh SEE ALSO 241.Xr getextattr 1 , 242.Xr extattr 3 , 243.Xr extattr 9 244.Sh HISTORY 245Extended attribute support was developed as part of the 246.Tn TrustedBSD 247Project, and introduced in 248.Fx 5.0 249and 250.Nx 3.0 . 251It was developed to support security extensions requiring additional labels 252to be associated with each file or directory. 253.Sh CAVEATS 254This interface is under active development, and as such is subject to 255change as applications are adapted to use it. 256Developers are discouraged from relying on its stability. 257