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 October 11, 2021
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.
152The
153.Qq Li _fd
154functions can be used with file descriptors opened with the
155.Dv O_PATH
156flag.
157.Pp
158The following arguments are common to all the system calls described here:
159.Bl -tag -width attrnamespace
160.It Fa attrnamespace
161the namespace in which the extended attribute resides; see
162.Xr extattr 9
163.It Fa attrname
164the name of the extended attribute
165.El
166.Pp
167Named extended attribute semantics vary by file system implementing the call.
168Not all operations may be supported for a particular attribute.
169Additionally, the format of the data in
170.Fa data
171is attribute-specific.
172.Pp
173For more information on named extended attributes, please see
174.Xr extattr 9 .
175.Sh RETURN VALUES
176If successful, the
177.Fn extattr_get_fd ,
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 ,
183.Fn extattr_set_fd ,
184.Fn extattr_set_file ,
185and
186.Fn extattr_set_link
187calls return the number of bytes
188that were read or written from the
189.Fa data ,
190respectively.
191If
192.Fa data
193was
194.Dv NULL ,
195then
196.Fn extattr_get_fd ,
197.Fn extattr_get_file ,
198.Fn extattr_get_link ,
199.Fn extattr_list_fd ,
200.Fn extattr_list_file ,
201and
202.Fn extattr_list_link
203return the number of bytes available to read.
204If any of the calls are unsuccessful, the value \-1 is returned
205and the global variable
206.Va errno
207is set to indicate the error.
208.Pp
209.Rv -std extattr_delete_file
210.Sh ERRORS
211The following errors may be returned by the system calls themselves.
212Additionally, the file system implementing the call may return any
213other errors it desires.
214.Bl -tag -width Er
215.It Bq Er EFAULT
216The
217.Fa attrnamespace
218and
219.Fa attrname
220arguments,
221or the memory range defined by
222.Fa data
223and
224.Fa nbytes
225point outside the process's allocated address space.
226.It Bq Er ENAMETOOLONG
227The attribute name was longer than
228.Dv EXTATTR_MAXNAMELEN .
229.El
230.Pp
231The
232.Fn extattr_get_fd ,
233.Fn extattr_set_fd ,
234.Fn extattr_delete_fd ,
235and
236.Fn extattr_list_fd
237system calls may also fail if:
238.Bl -tag -width Er
239.It Bq Er EBADF
240The file descriptor referenced by
241.Fa fd
242was invalid.
243.El
244.Pp
245Additionally, the
246.Fn extattr_get_file ,
247.Fn extattr_set_file ,
248and
249.Fn extattr_delete_file
250calls may also fail due to the following errors:
251.Bl -tag -width Er
252.It Bq Er ENOATTR
253The requested attribute was not defined for this file.
254.It Bq Er ENOTDIR
255A component of the path prefix is not a directory.
256.It Bq Er ENAMETOOLONG
257A component of a pathname exceeded 255 characters,
258or an entire path name exceeded 1023 characters.
259.It Bq Er ENOENT
260A component of the path name that must exist does not exist.
261.It Bq Er EACCES
262Search permission is denied for a component of the path prefix.
263.\" XXX are any missing?
264.El
265.Sh SEE ALSO
266.Xr extattr 3 ,
267.Xr getextattr 8 ,
268.Xr setextattr 8 ,
269.Xr extattr 9 ,
270.Xr VOP_GETEXTATTR 9 ,
271.Xr VOP_SETEXTATTR 9
272.Sh HISTORY
273Extended attribute support was developed as part of the
274.Tn TrustedBSD
275Project, and introduced in
276.Fx 5.0 .
277It was developed to support security extensions requiring additional labels
278to be associated with each file or directory.
279.Sh CAVEATS
280This interface is under active development, and as such is subject to
281change as applications are adapted to use it.
282Developers are discouraged from relying on its stability.
283.Sh BUGS
284In earlier versions of this API, passing an empty string for the
285attribute name to
286.Fn extattr_get_fd ,
287.Fn extattr_get_file ,
288or
289.Fn extattr_get_link
290would return the list of attributes defined for the target object.
291This interface has been deprecated in preference to using the explicit
292list API, and should not be used.
293