EXTATTR(2)                OpenBSD Programmer's Manual               EXTATTR(2)

NAME
     extattr_get_fd, extattr_set_fd, extattr_delete_fd, extattr_get_file,
     extattr_set_file, extattr_delete_file - system calls to manipulate VFS
     extended attributes

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_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);

DESCRIPTION
     Named extended attributes are meta-data associated with vnodes represent-
     ing files and directories.  They exist as "name=value" pairs within a set
     of namespaces.  The extattr_get_file() call retrieves the value of the
     specified extended attribute into a buffer pointed to by data of size
     nbytes.  The extattr_set_file() call sets the value of the specified ex-
     tended attribute to the data described by data.  The
     extattr_delete_file() call deletes the extended attribute specified.  The
     extattr_get_file() and extattr_set_file() calls consume the data and
     nbytes arguments in the style of read(2) and write(2), respectively.  If
     data is NULL in a call to extattr_get_file() then the size of defined ex-
     tended attribute data will be returned, rather than the quantity read,
     permitting applications to test the size of the data without performing a
     read.

     The extatttr_get_fd(), extattr_set_fd(), and extattr_delete_fd() calls
     are identical to their "_file" counterparts except for the first argu-
     ment.  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 filesystem 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, respective-
     ly, 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 er-
     ror.

     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.  Ad-
     ditionally, the filesystem implementing the call may return any other er-
     rors it desires.

     [EFAULT]      attrnamespace, attrname, or the memory range defined by
                   data and nbytes points outside the process's allocated ad-
                   dress space.

     [ENAMETOOLONG]
                   The attribute name was longer than EXTATTR_MAXNAMELEN.

     The extattr_get_fd(), extattr_set_fd(), and extattr_delete_fd() functions
     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:

     [ENOTDIR]     A component of the path prefix is not a directory.

     [ENAMETOOLONG]
                   A component of a pathname exceeded 255 characters, or an
                   entire path name exceeded 1023 characters.

     [ENOENT]      A component of the path name that must exist does not ex-
                   ist.

     [EACCES]      Search permission is denied for a component of the path
                   prefix.

     [ENOATTR]     An attribute does not exist for the specified existing
                   path.

SEE ALSO
     extattr(3), extattrctl(8), getextattr(8), setextattr(8), extattr(9)

HISTORY
     Extended attribute support was developed as part of the TrustedBSD Pro-
     ject, and introduced in OpenBSD 3.1.  It was developed to support securi-
     ty 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.

OpenBSD 3.5                     March 28, 2001                               2
