2 .\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
3 .\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
27 .\" $FreeBSD: src/lib/libc/sys/extattr_get_file.2,v 1.19 2008/01/29 18:15:38 trhodes Exp $
33 .Nm extattr_get_file ,
34 .Nm extattr_set_file ,
35 .Nm extattr_delete_file
36 .Nd system calls to manipulate VFS extended attributes
43 .Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
45 .Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
47 .Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
49 Named extended attributes are meta-data associated with vnodes
50 representing files and directories.
53 pairs within a set of namespaces.
57 system call retrieves the value of the specified extended attribute into
58 a buffer pointed to by
64 system call sets the value of the specified extended attribute to the data
68 .Fn extattr_delete_file
69 system call deletes the extended attribute specified.
76 arguments in the style of
79 consumes these arguments in the style of
88 then the size of defined extended attribute data will be returned, rather
89 than the quantity read, permitting applications to test the size of the
90 data without performing a read.
92 The following arguments are common to all the system calls described here:
93 .Bl -tag -width attrnamespace
95 the namespace in which the extended attribute resides; see
98 the name of the extended attribute
101 Named extended attribute semantics vary by file system implementing the call.
102 Not all operations may be supported for a particular attribute.
103 Additionally, the format of the data in
105 is attribute-specific.
107 For more information on named extended attributes, please see
110 This interface is under active development, and as such is subject to
111 change as applications are adapted to use it.
112 Developers are discouraged from relying on its stability.
118 calls return the number of bytes
119 that were read or written from the
127 returns the number of bytes available to read.
128 If any of the calls are unsuccessful, the value \-1 is returned
129 and the global variable
131 is set to indicate the error.
133 .Rv -std extattr_delete_file
135 The following errors may be returned by the system calls themselves.
136 Additionally, the file system implementing the call may return any
137 other errors it desires.
145 or the memory range defined by
149 point outside the process's allocated address space.
150 .It Bq Er ENAMETOOLONG
151 The attribute name was longer than
152 .Dv EXTATTR_MAXNAMELEN .
156 .Fn extattr_get_file ,
157 .Fn extattr_set_file ,
159 .Fn extattr_delete_file
160 calls may also fail due to the following errors:
163 The requested attribute was not defined for this file.
165 A component of the path prefix is not a directory.
166 .It Bq Er ENAMETOOLONG
167 A component of a pathname exceeded 255 characters,
168 or an entire path name exceeded 1023 characters.
170 A component of the path name that must exist does not exist.
172 Search permission is denied for a component of the path prefix.
173 .\" XXX are any missing?
177 .\".Xr getextattr 8 ,
178 .\".Xr setextattr 8 ,
180 .Xr VOP_GETEXTATTR 9 ,
183 Extended attribute support was developed as part of the
185 Project, and introduced in
187 It was developed to support security extensions requiring additional labels
188 to be associated with each file or directory.
190 In earlier versions of this API, passing an empty string for the
193 would return the list of attributes defined for the target object.
194 This interface has been deprecated in preference to using the explicit
195 list API, and should not be used.