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 December 7, 2020
30.Dt EXTATTR 2
31.Os
32.Sh NAME
33.Nm extattr_delete_fd ,
34.Nm extattr_delete_file ,
35.Nm extattr_delete_link ,
36.Nm extattr_get_fd ,
37.Nm extattr_get_file ,
38.Nm extattr_get_link ,
39.Nm extattr_list_fd ,
40.Nm extattr_list_file ,
41.Nm extattr_list_link ,
42.Nm extattr_set_fd ,
43.Nm extattr_set_file ,
44.Nm extattr_set_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 int
52.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
53.Ft int
54.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
55.Ft int
56.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
57.Ft ssize_t
58.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "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_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
63.Ft ssize_t
64.Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes"
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_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
69.Ft ssize_t
70.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
71.Ft ssize_t
72.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
73.Ft ssize_t
74.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const 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_delete_fd ,
139.Fn extattr_list_fd ,
140and
141.Fn extattr_set_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 RETURN VALUES
171If successful, the
172.Fn extattr_get_fd ,
173.Fn extattr_get_file ,
174.Fn extattr_get_link ,
175.Fn extattr_list_fd ,
176.Fn extattr_list_file ,
177.Fn extattr_list_link ,
178.Fn extattr_set_fd ,
179.Fn extattr_set_file ,
180and
181.Fn extattr_set_link
182calls return the number of bytes
183that were read or written from the
184.Fa data ,
185respectively.
186If
187.Fa data
188was
189.Dv NULL ,
190then
191.Fn extattr_get_fd ,
192.Fn extattr_get_file ,
193.Fn extattr_get_link ,
194.Fn extattr_list_fd ,
195.Fn extattr_list_file ,
196and
197.Fn extattr_list_link
198return the number of bytes available to read.
199If any of the calls are unsuccessful, the value \-1 is returned
200and the global variable
201.Va errno
202is set to indicate the error.
203.Pp
204.Rv -std extattr_delete_file
205.Sh ERRORS
206The following errors may be returned by the system calls themselves.
207Additionally, the file system implementing the call may return any
208other errors it desires.
209.Bl -tag -width Er
210.It Bq Er EFAULT
211The
212.Fa attrnamespace
213and
214.Fa attrname
215arguments,
216or the memory range defined by
217.Fa data
218and
219.Fa nbytes
220point outside the process's allocated address space.
221.It Bq Er ENAMETOOLONG
222The attribute name was longer than
223.Dv EXTATTR_MAXNAMELEN .
224.El
225.Pp
226The
227.Fn extattr_get_fd ,
228.Fn extattr_set_fd ,
229.Fn extattr_delete_fd ,
230and
231.Fn extattr_list_fd
232system calls may also fail if:
233.Bl -tag -width Er
234.It Bq Er EBADF
235The file descriptor referenced by
236.Fa fd
237was invalid.
238.El
239.Pp
240Additionally, the
241.Fn extattr_get_file ,
242.Fn extattr_set_file ,
243and
244.Fn extattr_delete_file
245calls may also fail due to the following errors:
246.Bl -tag -width Er
247.It Bq Er ENOATTR
248The requested attribute was not defined for this file.
249.It Bq Er ENOTDIR
250A component of the path prefix is not a directory.
251.It Bq Er ENAMETOOLONG
252A component of a pathname exceeded 255 characters,
253or an entire path name exceeded 1023 characters.
254.It Bq Er ENOENT
255A component of the path name that must exist does not exist.
256.It Bq Er EACCES
257Search permission is denied for a component of the path prefix.
258.\" XXX are any missing?
259.El
260.Sh SEE ALSO
261.Xr extattr 3 ,
262.Xr getextattr 8 ,
263.Xr setextattr 8 ,
264.Xr extattr 9 ,
265.Xr VOP_GETEXTATTR 9 ,
266.Xr VOP_SETEXTATTR 9
267.Sh HISTORY
268Extended attribute support was developed as part of the
269.Tn TrustedBSD
270Project, and introduced in
271.Fx 5.0 .
272It was developed to support security extensions requiring additional labels
273to be associated with each file or directory.
274.Sh CAVEATS
275This interface is under active development, and as such is subject to
276change as applications are adapted to use it.
277Developers are discouraged from relying on its stability.
278.Sh BUGS
279In earlier versions of this API, passing an empty string for the
280attribute name to
281.Fn extattr_get_fd ,
282.Fn extattr_get_file ,
283or
284.Fn extattr_get_link
285would return the list of attributes defined for the target object.
286This interface has been deprecated in preference to using the explicit
287list API, and should not be used.
288