NAME    [Toc]    [Back]

     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    [Toc]    [Back]

     #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    [Toc]    [Back]

     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()  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 extended
 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 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       extatttr_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 filesystem implementing the
     call.  Not all operations may be supported for a  particular
attribute.
     Additionally,  the  format of the data in data is attributespecific.

     For more information on named  extended  attributes,  please
see extattr(9).

RETURN VALUES    [Toc]    [Back]

     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    [Toc]    [Back]

     The following errors may be returned  by  the  system  calls
themselves.  Additionally,
  the filesystem implementing the call may return
any other errors
 it desires.

     [EFAULT]      attrnamespace, attrname, or the  memory  range
defined by
                   data  and  nbytes points 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() 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 exist.


     [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    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     Extended  attribute  support  was  developed  as part of the
TrustedBSD Project,
 and introduced in OpenBSD 3.1.  It  was  developed  to
support security
  extensions  requiring additional labels to be associated
with each file
     or directory.

CAVEATS    [Toc]    [Back]

     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.6                          March      28,      2001