1.\"
2.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
| 1.\"
2.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
|
26.\" $FreeBSD: head/lib/libc/sys/extattr_get_file.2 104737 2002-10-09 22:26:48Z rwatson $
| 26.\" $FreeBSD: head/lib/libc/sys/extattr_get_file.2 107788 2002-12-12 17:26:04Z ru $
|
27.\"
28.Dd March 28, 2001
29.Dt EXTATTR 2
30.Os
31.Sh NAME
32.Nm extattr_get_fd ,
33.Nm extattr_set_fd ,
34.Nm extattr_delete_fd ,
35.Nm extattr_get_file ,
36.Nm extattr_set_file ,
37.Nm extattr_delete_file
38.Nm extattr_get_link ,
39.Nm extattr_set_link ,
40.Nm extattr_delete_link
41.Nd system calls to manipulate VFS extended attributes
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In sys/types.h
46.In sys/extattr.h
47.In sys/uio.h
48.Ft ssize_t
49.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
50.Ft int
51.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
52.Ft int
53.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
54.Ft ssize_t
55.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
56.Ft int
57.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
58.Ft int
59.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
60.Ft ssize_t
61.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
62.Ft int
63.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
64.Ft int
65.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
66.Sh DESCRIPTION
67Named extended attributes are meta-data associated with vnodes
68representing files and directories.
69They exist as
70.Qq Li name=value
71pairs within a set of namespaces.
72The
73.Fn extattr_get_file
74call retrieves the value of the specified extended attribute into
75a buffer pointed to by
76.Fa data
77of size
78.Fa nbytes .
79The
80.Fn extattr_set_file
81call sets the value of the specified extended attribute to the data
82described by
83.Fa data .
84The
85.Fn extattr_delete_file
86call deletes the extended attribute specified.
87The
88.Fn extattr_get_file
89and
90.Fn extattr_set_file
91calls consume the
92.Fa data
93and
94.Fa nbytes
95arguments in the style of
96.Xr read 2
97and
98.Xr write 2 ,
99respectively.
100If
101.Fa data
102is
103.Dv NULL
104in a call to
105.Fn extattr_get_file
106then the size of defined extended attribute data will be returned, rather
107than the quantity read, permitting applications to test the size of the
108data without performing a read.
109The
110.Fn extattr_delete_link ,
111.Fn extattr_get_link ,
112and
113.Fn extattr_set_link
114functions behave in the same way as their _file counterparts, except that
115they do not follow symlinks.
116.Pp
117The
118.Fn extatttr_get_fd ,
119.Fn extattr_set_fd ,
120and
121.Fn extattr_delete_fd
122calls are identical to their
123.Qq Li _file
124counterparts except for the first argument.
125The
126.Qq Li _fd
127functions take a file descriptor, while the
128.Qq Li _file
129functions take a path.
130Both arguments describe a file associated with the extended attribute
131that should be manipulated.
132.Pp
133The following arguments are common to all the system calls described here:
134.Bl -tag -width attrnamespace
135.It Fa attrnamespace
136the namespace in which the extended attribute resides; see
137.Xr extattr 9
138.It Fa attrname
139the name of the extended attribute
140.El
141.Pp
| 27.\"
28.Dd March 28, 2001
29.Dt EXTATTR 2
30.Os
31.Sh NAME
32.Nm extattr_get_fd ,
33.Nm extattr_set_fd ,
34.Nm extattr_delete_fd ,
35.Nm extattr_get_file ,
36.Nm extattr_set_file ,
37.Nm extattr_delete_file
38.Nm extattr_get_link ,
39.Nm extattr_set_link ,
40.Nm extattr_delete_link
41.Nd system calls to manipulate VFS extended attributes
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In sys/types.h
46.In sys/extattr.h
47.In sys/uio.h
48.Ft ssize_t
49.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
50.Ft int
51.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
52.Ft int
53.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
54.Ft ssize_t
55.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
56.Ft int
57.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
58.Ft int
59.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
60.Ft ssize_t
61.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
62.Ft int
63.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
64.Ft int
65.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
66.Sh DESCRIPTION
67Named extended attributes are meta-data associated with vnodes
68representing files and directories.
69They exist as
70.Qq Li name=value
71pairs within a set of namespaces.
72The
73.Fn extattr_get_file
74call retrieves the value of the specified extended attribute into
75a buffer pointed to by
76.Fa data
77of size
78.Fa nbytes .
79The
80.Fn extattr_set_file
81call sets the value of the specified extended attribute to the data
82described by
83.Fa data .
84The
85.Fn extattr_delete_file
86call deletes the extended attribute specified.
87The
88.Fn extattr_get_file
89and
90.Fn extattr_set_file
91calls consume the
92.Fa data
93and
94.Fa nbytes
95arguments in the style of
96.Xr read 2
97and
98.Xr write 2 ,
99respectively.
100If
101.Fa data
102is
103.Dv NULL
104in a call to
105.Fn extattr_get_file
106then the size of defined extended attribute data will be returned, rather
107than the quantity read, permitting applications to test the size of the
108data without performing a read.
109The
110.Fn extattr_delete_link ,
111.Fn extattr_get_link ,
112and
113.Fn extattr_set_link
114functions behave in the same way as their _file counterparts, except that
115they do not follow symlinks.
116.Pp
117The
118.Fn extatttr_get_fd ,
119.Fn extattr_set_fd ,
120and
121.Fn extattr_delete_fd
122calls are identical to their
123.Qq Li _file
124counterparts except for the first argument.
125The
126.Qq Li _fd
127functions take a file descriptor, while the
128.Qq Li _file
129functions take a path.
130Both arguments describe a file associated with the extended attribute
131that should be manipulated.
132.Pp
133The following arguments are common to all the system calls described here:
134.Bl -tag -width attrnamespace
135.It Fa attrnamespace
136the namespace in which the extended attribute resides; see
137.Xr extattr 9
138.It Fa attrname
139the name of the extended attribute
140.El
141.Pp
|
142Named extended attribute semantics vary by filesystem implementing the call.
| 142Named extended attribute semantics vary by file system implementing the call.
|
143Not all operations may be supported for a particular attribute.
144Additionally, the format of the data in
145.Fa data
146is attribute-specific.
147.Pp
148For more information on named extended attributes, please see
149.Xr extattr 9 .
150.Sh CAVEAT
151This interface is under active development, and as such is subject to
152change as applications are adapted to use it.
153Developers are discouraged from relying on its stability.
154.Sh RETURN VALUES
155If successful, the
156.Fn extattr_get_file
157and
158.Fn extattr_set_file
159calls return the number of bytes
160that were read or written from the
161.Fa data ,
162respectively, or if
163.Fa data
164was
165.Dv NULL ,
166then
167.Fn extattr_get_file
168returns the number of bytes available to read.
169If any of the calls are unsuccessful, the value \-1 is returned
170and the global variable
171.Va errno
172is set to indicate the error.
173.Pp
174.Rv -std extattr_delete_file
175.Sh ERRORS
176The following errors may be returned by the system calls themselves.
| 143Not all operations may be supported for a particular attribute.
144Additionally, the format of the data in
145.Fa data
146is attribute-specific.
147.Pp
148For more information on named extended attributes, please see
149.Xr extattr 9 .
150.Sh CAVEAT
151This interface is under active development, and as such is subject to
152change as applications are adapted to use it.
153Developers are discouraged from relying on its stability.
154.Sh RETURN VALUES
155If successful, the
156.Fn extattr_get_file
157and
158.Fn extattr_set_file
159calls return the number of bytes
160that were read or written from the
161.Fa data ,
162respectively, or if
163.Fa data
164was
165.Dv NULL ,
166then
167.Fn extattr_get_file
168returns the number of bytes available to read.
169If any of the calls are unsuccessful, the value \-1 is returned
170and the global variable
171.Va errno
172is set to indicate the error.
173.Pp
174.Rv -std extattr_delete_file
175.Sh ERRORS
176The following errors may be returned by the system calls themselves.
|
177Additionally, the filesystem implementing the call may return any
| 177Additionally, the file system implementing the call may return any
|
178other errors it desires.
179.Bl -tag -width Er
180.It Bq Er EFAULT
181.Fa attrnamespace ,
182.Fa attrname ,
183or the memory range defined by
184.Fa data
185and
186.Fa nbytes
187points outside the process's allocated address space.
188.It Bq Er ENAMETOOLONG
189The attribute name was longer than
190.Dv EXTATTR_MAXNAMELEN .
191.El
192.Pp
193The
194.Fn extattr_get_fd ,
195.Fn extattr_set_fd ,
196and
197.Fn extattr_delete_fd
198functions may also fail if:
199.Bl -tag -width Er
200.It Bq Er EBADF
201The file descriptor referenced by
202.Fa fd
203was invalid.
204.El
205.Pp
206Additionally, the
207.Fn extattr_get_file ,
208.Fn extattr_set_file ,
209and
210.Fn extattr_delete_file
211calls may also fail due to the following errors:
212.Bl -tag -width Er
213.It Bq Er ENOTDIR
214A component of the path prefix is not a directory.
215.It Bq Er ENAMETOOLONG
216A component of a pathname exceeded 255 characters,
217or an entire path name exceeded 1023 characters.
218.It Bq Er ENOENT
219A component of the path name that must exist does not exist.
220.It Bq Er EACCES
221Search permission is denied for a component of the path prefix.
222.\" XXX are any missing?
223.El
224.Sh SEE ALSO
225.Xr extattr 3 ,
226.Xr getextattr 8 ,
227.Xr setextattr 8 ,
228.Xr extattr 9 ,
229.Xr VOP_GETEXTATTR 9 ,
230.Xr VOP_SETEXTATTR 9
231.Sh HISTORY
232Extended attribute support was developed as part of the
233.Tn TrustedBSD
234Project, and introduced in
235.Fx 5.0 .
236It was developed to support security extensions requiring additional labels
237to be associated with each file or directory.
| 178other errors it desires.
179.Bl -tag -width Er
180.It Bq Er EFAULT
181.Fa attrnamespace ,
182.Fa attrname ,
183or the memory range defined by
184.Fa data
185and
186.Fa nbytes
187points outside the process's allocated address space.
188.It Bq Er ENAMETOOLONG
189The attribute name was longer than
190.Dv EXTATTR_MAXNAMELEN .
191.El
192.Pp
193The
194.Fn extattr_get_fd ,
195.Fn extattr_set_fd ,
196and
197.Fn extattr_delete_fd
198functions may also fail if:
199.Bl -tag -width Er
200.It Bq Er EBADF
201The file descriptor referenced by
202.Fa fd
203was invalid.
204.El
205.Pp
206Additionally, the
207.Fn extattr_get_file ,
208.Fn extattr_set_file ,
209and
210.Fn extattr_delete_file
211calls may also fail due to the following errors:
212.Bl -tag -width Er
213.It Bq Er ENOTDIR
214A component of the path prefix is not a directory.
215.It Bq Er ENAMETOOLONG
216A component of a pathname exceeded 255 characters,
217or an entire path name exceeded 1023 characters.
218.It Bq Er ENOENT
219A component of the path name that must exist does not exist.
220.It Bq Er EACCES
221Search permission is denied for a component of the path prefix.
222.\" XXX are any missing?
223.El
224.Sh SEE ALSO
225.Xr extattr 3 ,
226.Xr getextattr 8 ,
227.Xr setextattr 8 ,
228.Xr extattr 9 ,
229.Xr VOP_GETEXTATTR 9 ,
230.Xr VOP_SETEXTATTR 9
231.Sh HISTORY
232Extended attribute support was developed as part of the
233.Tn TrustedBSD
234Project, and introduced in
235.Fx 5.0 .
236It was developed to support security extensions requiring additional labels
237to be associated with each file or directory.
|