2 .\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
3 .\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nm extattr_delete_fd ,
34 .Nm extattr_delete_file ,
35 .Nm extattr_delete_link ,
37 .Nm extattr_get_file ,
38 .Nm extattr_get_link ,
40 .Nm extattr_list_file ,
41 .Nm extattr_list_link ,
43 .Nm extattr_set_file ,
45 .Nd system calls to manipulate VFS extended attributes
52 .Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
54 .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
56 .Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
58 .Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
60 .Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
62 .Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
64 .Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes"
66 .Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
68 .Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
70 .Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
72 .Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
74 .Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
76 Named extended attributes are meta-data associated with vnodes
77 representing files and directories.
80 pairs within a set of namespaces.
84 system call retrieves the value of the specified extended attribute into
85 a buffer pointed to by
91 system call sets the value of the specified extended attribute to the data
95 .Fn extattr_delete_file
96 system call deletes the extended attribute specified.
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).
106 .Fn extattr_list_file
111 arguments in the style of
114 consumes these arguments in the style of
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.
129 .Fn extattr_delete_link ,
130 .Fn extattr_get_link ,
133 system calls behave in the same way as their _file counterparts, except that
134 they do not follow symlinks.
138 .Fn extattr_delete_fd ,
139 .Fn extattr_list_fd ,
142 calls are identical to their
144 counterparts except for the first argument.
147 functions take a file descriptor, while the
149 functions take a path.
150 Both arguments describe a file associated with the extended attribute
151 that should be manipulated.
154 functions can be used with file descriptors opened with the
158 The following arguments are common to all the system calls described here:
159 .Bl -tag -width attrnamespace
161 the namespace in which the extended attribute resides; see
164 the name of the extended attribute
167 Named extended attribute semantics vary by file system implementing the call.
168 Not all operations may be supported for a particular attribute.
169 Additionally, the format of the data in
171 is attribute-specific.
173 For more information on named extended attributes, please see
178 .Fn extattr_get_file ,
179 .Fn extattr_get_link ,
180 .Fn extattr_list_fd ,
181 .Fn extattr_list_file ,
182 .Fn extattr_list_link ,
184 .Fn extattr_set_file ,
187 calls return the number of bytes
188 that were read or written from the
197 .Fn extattr_get_file ,
198 .Fn extattr_get_link ,
199 .Fn extattr_list_fd ,
200 .Fn extattr_list_file ,
202 .Fn extattr_list_link
203 return the number of bytes available to read.
204 If any of the calls are unsuccessful, the value \-1 is returned
205 and the global variable
207 is set to indicate the error.
209 .Rv -std extattr_delete_file
211 The following errors may be returned by the system calls themselves.
212 Additionally, the file system implementing the call may return any
213 other errors it desires.
221 or the memory range defined by
225 point outside the process's allocated address space.
226 .It Bq Er ENAMETOOLONG
227 The attribute name was longer than
228 .Dv EXTATTR_MAXNAMELEN .
234 .Fn extattr_delete_fd ,
237 system calls may also fail if:
240 The file descriptor referenced by
246 .Fn extattr_get_file ,
247 .Fn extattr_set_file ,
249 .Fn extattr_delete_file
250 calls may also fail due to the following errors:
253 The requested attribute was not defined for this file.
255 A component of the path prefix is not a directory.
256 .It Bq Er ENAMETOOLONG
257 A component of a pathname exceeded 255 characters,
258 or an entire path name exceeded 1023 characters.
260 A component of the path name that must exist does not exist.
262 Search permission is denied for a component of the path prefix.
263 .\" XXX are any missing?
270 .Xr VOP_GETEXTATTR 9 ,
273 Extended attribute support was developed as part of the
275 Project, and introduced in
277 It was developed to support security extensions requiring additional labels
278 to be associated with each file or directory.
280 This interface is under active development, and as such is subject to
281 change as applications are adapted to use it.
282 Developers are discouraged from relying on its stability.
284 In earlier versions of this API, passing an empty string for the
287 .Fn extattr_get_file ,
290 would return the list of attributes defined for the target object.
291 This interface has been deprecated in preference to using the explicit
292 list API, and should not be used.