Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
EXTATTR(2)		  FreeBSD System Calls Manual		    EXTATTR(2)

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 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_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() 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 sym-
     links.

     The extattr_get_fd(), extattr_set_fd(), extattr_delete_fd(), and
     extattr_list_fd(),	calls are identical to their "_file" counterparts
     except for	the first argument.  The "_fd" functions take a	file descrip-
     tor, 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).

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 data, respectively, or if	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.

     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.

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

     [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(3), getextattr(8),	setextattr(8), 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_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.

FreeBSD	9.3		       January 29, 2008			   FreeBSD 9.3

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | CAVEAT | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=2&manpath=FreeBSD+9.2-RELEASE>

home | help