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 March 28, 2001
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.In sys/uio.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.
125The
126.Fn extattr_delete_link ,
127.Fn extattr_get_link ,
128and
129.Fn extattr_set_link
130system calls behave in the same way as their _file counterparts, except that
131they do not follow symlinks.
132.Pp
133The
134.Fn extattr_get_fd ,
135.Fn extattr_set_fd ,
136and
137.Fn extattr_delete_fd
138calls are identical to their
139.Qq Li _file
140counterparts except for the first argument.
141The
142.Qq Li _fd
143functions take a file descriptor, while the
144.Qq Li _file
145functions take a path.
146Both arguments describe a file associated with the extended attribute
147that should be manipulated.
148.Pp
149The following arguments are common to all the system calls described here:
150.Bl -tag -width attrnamespace
151.It Fa attrnamespace
152the namespace in which the extended attribute resides; see
153.Xr extattr 9
154.It Fa attrname
155the name of the extended attribute
156.El
157.Pp
158Named extended attribute semantics vary by file system implementing the call.
159Not all operations may be supported for a particular attribute.
160Additionally, the format of the data in
161.Fa data
162is attribute-specific.
163.Pp
164For more information on named extended attributes, please see
165.Xr extattr 9 .
166.Sh CAVEAT
167This interface is under active development, and as such is subject to
168change as applications are adapted to use it.
169Developers are discouraged from relying on its stability.
170.Sh RETURN VALUES
171If successful, the
172.Fn extattr_get_file
173and
174.Fn extattr_set_file
175calls return the number of bytes
176that were read or written from the
177.Fa data ,
178respectively, or if
179.Fa data
180was
181.Dv NULL ,
182then
183.Fn extattr_get_file
184returns the number of bytes available to read.
185If any of the calls are unsuccessful, the value \-1 is returned
186and the global variable
187.Va errno
188is set to indicate the error.
189.Pp
190.Rv -std extattr_delete_file
191.Sh ERRORS
192The following errors may be returned by the system calls themselves.
193Additionally, the file system implementing the call may return any
194other errors it desires.
195.Bl -tag -width Er
196.It Bq Er EFAULT
197The
198.Fa attrnamespace
199and
200.Fa attrname
201arguments,
202or the memory range defined by
203.Fa data
204and
205.Fa nbytes
206point outside the process's allocated address space.
207.It Bq Er ENAMETOOLONG
208The attribute name was longer than
209.Dv EXTATTR_MAXNAMELEN .
210.El
211.Pp
212The
213.Fn extattr_get_fd ,
214.Fn extattr_set_fd ,
215and
216.Fn extattr_delete_fd
217system calls may also fail if:
218.Bl -tag -width Er
219.It Bq Er EBADF
220The file descriptor referenced by
221.Fa fd
222was invalid.
223.El
224.Pp
225Additionally, the
226.Fn extattr_get_file ,
227.Fn extattr_set_file ,
228and
229.Fn extattr_delete_file
230calls may also fail due to the following errors:
231.Bl -tag -width Er
232.It Bq Er ENOTDIR
233A component of the path prefix is not a directory.
234.It Bq Er ENAMETOOLONG
235A component of a pathname exceeded 255 characters,
236or an entire path name exceeded 1023 characters.
237.It Bq Er ENOENT
238A component of the path name that must exist does not exist.
239.It Bq Er EACCES
240Search permission is denied for a component of the path prefix.
241.\" XXX are any missing?
242.El
243.Sh SEE ALSO
244.Xr extattr 3 ,
245.Xr getextattr 8 ,
246.Xr setextattr 8 ,
247.Xr extattr 9 ,
248.Xr VOP_GETEXTATTR 9 ,
249.Xr VOP_SETEXTATTR 9
250.Sh HISTORY
251Extended attribute support was developed as part of the
252.Tn TrustedBSD
253Project, and introduced in
254.Fx 5.0 .
255It was developed to support security extensions requiring additional labels
256to be associated with each file or directory.
257.Sh BUGS
258In earlier versions of this API, passing an empty string for the
259attribute name to
260.Fn extattr_get_fd ,
261.Fn extattr_get_file ,
262or
263.Fn extattr_get_link
264would return the list of attributes defined for the target object.
265This interface has been deprecated in preference to using the explicit
266list API, and should not be used.
267