EXTATTR(2)		    BSD System Calls Manual		    EXTATTR(2)

NAME
     extattr_get_file, extattr_set_file, extattr_delete_file — 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_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() 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() sys‐
     tem call deletes the extended attribute specified.	 The
     extattr_get_file() call consumes 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 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).

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() and extattr_set_file() calls return
     the number of bytes that were read or written from the data, respec‐
     tively, 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 mem‐
			ory range defined by data and nbytes point outside the
			process's allocated address space.

     [ENAMETOOLONG]	The attribute name was longer than EXTATTR_MAXNAMELEN.

     Additionally, the extattr_get_file(), extattr_set_file(), and
     extattr_delete_file() calls may also fail due to the following errors:

     [ENOATTR]		The requested attribute was not defined for this file.

     [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.

SEE ALSO
     extattr(9), VOP_GETEXTATTR(9), VOP_SETEXTATTR(9)

HISTORY
     Extended attribute support was developed as part of the TrustedBSD
     Project, and introduced in FreeBSD 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_file() 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.

BSD				  May 8, 2010				   BSD

Vote for polarhome