1.\"
2.\" Copyright (c) 2001 Dima Dorfman <[email protected]>
3.\" Copyright (c) 2003 Robert Watson <[email protected]>
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$
28.\"
29.Dd January 29, 2008
30.Dt EXTATTR 2
31.Os
32.Sh NAME
33.Nm extattr_get_fd ,
34.Nm extattr_set_fd ,
35.Nm extattr_delete_fd ,
36.Nm extattr_list_fd ,
37.Nm extattr_get_file ,
38.Nm extattr_set_file ,
39.Nm extattr_delete_file ,
40.Nm extattr_list_file ,
41.Nm extattr_get_link ,
42.Nm extattr_set_link ,
43.Nm extattr_delete_link ,
44.Nm extattr_list_link
45.Nd system calls to manipulate VFS extended attributes
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In sys/types.h
50.In sys/extattr.h
51.Ft ssize_t
52.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
53.Ft ssize_t
54.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
55.Ft int
56.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
57.Ft ssize_t
58.Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes"
59.Ft ssize_t
60.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
61.Ft ssize_t
62.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
63.Ft int
64.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
65.Ft ssize_t
66.Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
67.Ft ssize_t
68.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
69.Ft ssize_t
70.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
71.Ft int
72.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
73.Ft ssize_t
74.Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
75.Sh DESCRIPTION
76Named extended attributes are meta-data associated with vnodes
77representing files and directories.
78They exist as
79.Qq Li name=value
80pairs within a set of namespaces.
81.Pp
82The
83.Fn extattr_get_file
84system call retrieves the value of the specified extended attribute into
85a buffer pointed to by
86.Fa data
87of size
88.Fa nbytes .
89The
90.Fn extattr_set_file
91system call sets the value of the specified extended attribute to the data
92described by
93.Fa data .
94The
95.Fn extattr_delete_file
96system call deletes the extended attribute specified.
97The
98.Fn extattr_list_file
99returns a list of attributes present in the requested namespace.
100Each list entry consists of a single byte containing the length
101of the attribute name, followed by the attribute name.
102The attribute name is not terminated by ASCII 0 (nul).
103The
104.Fn extattr_get_file ,
105and
106.Fn extattr_list_file
107calls consume the
108.Fa data
109and
110.Fa nbytes
111arguments in the style of
112.Xr read 2 ;
113.Fn extattr_set_file
114consumes these arguments in the style of
115.Xr write 2 .
116.Pp
117If
118.Fa data
119is
120.Dv NULL
121in a call to
122.Fn extattr_get_file
123and
124.Fn extattr_list_file
125then the size of defined extended attribute data will be returned, rather
126than the quantity read, permitting applications to test the size of the
127data without performing a read.
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 ,
139.Fn extattr_delete_fd ,
140and
141.Fn extattr_list_fd ,
142calls are identical to their
143.Qq Li _file
144counterparts except for the first argument.
145The
146.Qq Li _fd
147functions take a file descriptor, while the
148.Qq Li _file
149functions take a path.
150Both arguments describe a file associated with the extended attribute
151that should be manipulated.
152.Pp
153The following arguments are common to all the system calls described here:
154.Bl -tag -width attrnamespace
155.It Fa attrnamespace
156the namespace in which the extended attribute resides; see
157.Xr extattr 9
158.It Fa attrname
159the name of the extended attribute
160.El
161.Pp
162Named extended attribute semantics vary by file system implementing the call.
163Not all operations may be supported for a particular attribute.
164Additionally, the format of the data in
165.Fa data
166is attribute-specific.
167.Pp
168For more information on named extended attributes, please see
169.Xr extattr 9 .
170.Sh CAVEAT
171This interface is under active development, and as such is subject to
172change as applications are adapted to use it.
173Developers are discouraged from relying on its stability.
174.Sh RETURN VALUES
175If successful, the
176.Fn extattr_get_file ,
177.Fn extattr_set_file ,
178and
179.Fn extattr_list_file
180calls return the number of bytes
181that were read or written from the
182.Fa data ,
183respectively, or if
184.Fa data
185was
186.Dv NULL ,
187then
188.Fn extattr_get_file
189and
190.Fn extattr_list_file
191return the number of bytes available to read.
192If any of the calls are unsuccessful, the value \-1 is returned
193and the global variable
194.Va errno
195is set to indicate the error.
196.Pp
197.Rv -std extattr_delete_file
198.Sh ERRORS
199The following errors may be returned by the system calls themselves.
200Additionally, the file system implementing the call may return any
201other errors it desires.
202.Bl -tag -width Er
203.It Bq Er EFAULT
204The
205.Fa attrnamespace
206and
207.Fa attrname
208arguments,
209or the memory range defined by
210.Fa data
211and
212.Fa nbytes
213point outside the process's allocated address space.
214.It Bq Er ENAMETOOLONG
215The attribute name was longer than
216.Dv EXTATTR_MAXNAMELEN .
217.El
218.Pp
219The
220.Fn extattr_get_fd ,
221.Fn extattr_set_fd ,
222.Fn extattr_delete_fd ,
223and
224.Fn extattr_list_fd
225system calls may also fail if:
226.Bl -tag -width Er
227.It Bq Er EBADF
228The file descriptor referenced by
229.Fa fd
230was invalid.
231.El
232.Pp
233Additionally, the
234.Fn extattr_get_file ,
235.Fn extattr_set_file ,
236and
237.Fn extattr_delete_file
238calls may also fail due to the following errors:
239.Bl -tag -width Er
240.It Bq Er ENOATTR
241The requested attribute was not defined for this file.
242.It Bq Er ENOTDIR
243A component of the path prefix is not a directory.
244.It Bq Er ENAMETOOLONG
245A component of a pathname exceeded 255 characters,
246or an entire path name exceeded 1023 characters.
247.It Bq Er ENOENT
248A component of the path name that must exist does not exist.
249.It Bq Er EACCES
250Search permission is denied for a component of the path prefix.
251.\" XXX are any missing?
252.El
253.Sh SEE ALSO
254.Xr extattr 3 ,
255.Xr getextattr 8 ,
256.Xr setextattr 8 ,
257.Xr extattr 9 ,
258.Xr VOP_GETEXTATTR 9 ,
259.Xr VOP_SETEXTATTR 9
260.Sh HISTORY
261Extended attribute support was developed as part of the
262.Tn TrustedBSD
263Project, and introduced in
264.Fx 5.0 .
265It was developed to support security extensions requiring additional labels
266to be associated with each file or directory.
267.Sh BUGS
268In earlier versions of this API, passing an empty string for the
269attribute name to
270.Fn extattr_get_fd ,
271.Fn extattr_get_file ,
272or
273.Fn extattr_get_link
274would return the list of attributes defined for the target object.
275This interface has been deprecated in preference to using the explicit
276list API, and should not be used.
277