NAME
extattr_get_fd,
extattr_set_fd,
extattr_delete_fd,
extattr_list_fd,
extattr_get_file,
extattr_set_file,
extattr_delete_file,
extattr_list_file,
extattr_get_link,
extattr_set_link,
extattr_delete_link,
extattr_list_link
—
system calls to manipulate VFS extended
attributes
LIBRARY
Standard C Library (libc, -lc)
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
“
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
data of size
nbytes. The
extattr_set_file() system call sets the value of the
specified extended attribute to the data described by
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
data and
nbytes
arguments in the style of
read(2);
extattr_set_file() consumes these arguments in the style of
write(2).
If
data is
NULL
in a call to
extattr_get_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(), and
extattr_delete_fd() calls are identical to their
“
_file
” counterparts except for the first
argument. The “
_fd
” functions take a file
descriptor, while the “
_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:
-
-
- attrnamespace
- the namespace in which the extended attribute resides; see
extattr(9)
-
-
- 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
data is attribute-specific.
For more information on named extended attributes, please see
extattr(9).
RETURN VALUES
If successful, the
extattr_get_file() and
extattr_set_file() calls return the number of bytes that
were read or written from the
data, respectively, or if
data was
NULL
, then
extattr_get_file() returns 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.
The
extattr_delete_file() function returns the value 0 if
successful; otherwise the value -1 is returned and the global variable
errno is set to indicate the error.
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.
-
-
- [
EFAULT
]
- The attrnamespace and
attrname arguments, or the memory range defined by
data and nbytes point outside
the process's allocated address space.
-
-
- [
ENAMETOOLONG
]
- The attribute name was longer than
EXTATTR_MAXNAMELEN
.
The
extattr_get_fd(),
extattr_set_fd(), and
extattr_delete_fd() system calls may also fail if:
-
-
- [
EBADF
]
- The file descriptor referenced by fd
was invalid.
Additionally, the
extattr_get_file(),
extattr_set_file(), and
extattr_delete_file() calls may also fail due to the
following errors:
-
-
- [
EACCES
]
- Search permission is denied for a component of the path
prefix.
-
-
- [
ENAMETOOLONG
]
- A component of a pathname exceeded
{
NAME_MAX
} characters, or an entire path name
exceeded {PATH_MAX
} characters.
-
-
- [
ENOENT
]
- A component of the path name that must exist does not
exist.
-
-
- [
ENOTDIR
]
- A component of the path prefix is not a directory.
SEE ALSO
getextattr(1),
extattr(3),
extattr(9)
HISTORY
Extended attribute support was developed as part of the TrustedBSD Project, and
introduced in
FreeBSD 5.0 and
NetBSD
3.0. It was developed to support security extensions requiring
additional labels to be associated with each file or directory.
CAVEATS
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.
Note that previous versions of this man page incorrectly stated that
extattr_list_file() returned a list of attribute names
separated by ASCII 0 (nul).