extattr_get_fdextattr_set_fdextattr_delete_fdextattr_list_fdextattr_get_fileextattr_set_fileextattr_delete_fileextattr_list_fileextattr_get_linkextattr_set_linkextattr_delete_linkextattr_list_link
- system calls to manipulate VFS extended attributes
LIBRARY
Lb libc
SYNOPSIS
#include <sys/types.h>
#include <sys/extattr.h> ssize_t
extattr_get_fd (int fd int attrnamespace const char *attrname void *data size_t nbytes); int
extattr_set_fd (int fd int attrnamespace const char *attrname const void *data size_t nbytes); int
extattr_delete_fd (int fd int attrnamespace const char *attrname); ssize_t
extattr_list_fd (int fd int attrnamespace void *data size_t nbytes); ssize_t
extattr_get_file (const char *path int attrnamespace const char *attrname void *data size_t nbytes); int
extattr_set_file (const char *path int attrnamespace const char *attrname const void *data size_t nbytes); int
extattr_delete_file (const char *path int attrnamespace const char *attrname); ssize_t
extattr_list_file (const char *path int attrnamespace void *data size_t nbytes); ssize_t
extattr_get_link (const char *path int attrnamespace const char *attrname void *data size_t nbytes); int
extattr_set_link (const char *path int attrnamespace const char *attrname const void *data size_t nbytes); int
extattr_delete_link (const char *path int attrnamespace const char *attrname); ssize_t
extattr_list_link (const char *path int attrnamespace void *data size_t nbytes);
DESCRIPTION
Named extended attributes are meta-data associated with vnodes
representing files and directories.
They exist as
Qq Li name=value
pairs within a set of namespaces.
The
extattr_get_file ();
system call retrieves the value of the specified extended attribute into
a buffer pointed to by
Fa data
of size
Fa nbytes .
The
extattr_set_file ();
system call sets the value of the specified extended attribute to the data
described by
Fa data .
The
extattr_delete_file ();
system call deletes the extended attribute specified.
The
extattr_list_file ();
returns a list of attributes present in the requested namespace.
Each list entry consists of a single byte containing the length
of the attribute name, followed by the attribute name.
The attribute name is not terminated by ASCII 0 (nul).
The
extattr_get_file (,);
and
extattr_list_file ();
calls consume the
Fa data
and
Fa nbytes
arguments in the style of
read(2);
extattr_set_file ();
consumes these arguments in the style of
write(2).
If
Fa data
is
NULL
in a call to
extattr_get_file ();
and
extattr_list_file ();
then the size of defined extended attribute data will be returned, rather
than the quantity read, permitting applications to test the size of the
data without performing a read.
The
extattr_delete_link (,);
extattr_get_link (,);
and
extattr_set_link ();
system calls behave in the same way as their _file counterparts, except that
they do not follow symlinks.
The
extattr_get_fd (,);
extattr_set_fd (,);
extattr_delete_fd (,);
and
extattr_list_fd (,);
calls are identical to their
Qq Li _file
counterparts except for the first argument.
The
Qq Li _fd
functions take a file descriptor, while the
Qq Li _file
functions take a path.
Both arguments describe a file associated with the extended attribute
that should be manipulated.
The following arguments are common to all the system calls described here:
Fa attrnamespace
the namespace in which the extended attribute resides; see
extattr(9)
Fa attrname
the name of the extended attribute
Named extended attribute semantics vary by file system implementing the call.
Not all operations may be supported for a particular attribute.
Additionally, the format of the data in
Fa data
is attribute-specific.
For more information on named extended attributes, please see
extattr(9).
CAVEAT
This interface is under active development, and as such is subject to
change as applications are adapted to use it.
Developers are discouraged from relying on its stability.
RETURN VALUES
If successful, the
extattr_get_file (,);
extattr_set_file (,);
and
extattr_list_file ();
calls return the number of bytes
that were read or written from the
Fa data ,
respectively, or if
Fa data
was
NULL
then
extattr_get_file ();
and
extattr_list_file ();
return the number of bytes available to read.
If any of the calls are unsuccessful, the value -1 is returned
and the global variable
errno
is set to indicate the error.
Rv -std extattr_delete_file
ERRORS
The following errors may be returned by the system calls themselves.
Additionally, the file system implementing the call may return any
other errors it desires.
Bq Er EFAULT
The
Fa attrnamespace
and
Fa attrname
arguments,
or the memory range defined by
Fa data
and
Fa nbytes
point outside the process's allocated address space.
Bq Er ENAMETOOLONG
The attribute name was longer than
EXTATTR_MAXNAMELEN
The
extattr_get_fd (,);
extattr_set_fd (,);
extattr_delete_fd (,);
and
extattr_list_fd ();
system calls may also fail if:
Bq Er EBADF
The file descriptor referenced by
Fa fd
was invalid.
Additionally, the
extattr_get_file (,);
extattr_set_file (,);
and
extattr_delete_file ();
calls may also fail due to the following errors:
Bq Er ENOATTR
The requested attribute was not defined for this file.
Bq Er ENOTDIR
A component of the path prefix is not a directory.
Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
Bq Er ENOENT
A component of the path name that must exist does not exist.
Bq Er EACCES
Search permission is denied for a component of the path prefix.
Extended attribute support was developed as part of the
TrustedBSD
Project, and introduced in
Fx 5.0 .
It was developed to support security extensions requiring additional labels
to be associated with each file or directory.
BUGS
In earlier versions of this API, passing an empty string for the
attribute name to
extattr_get_fd (,);
extattr_get_file (,);
or
extattr_get_link ();
would return the list of attributes defined for the target object.
This interface has been deprecated in preference to using the explicit
list API, and should not be used.
