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

FreeBSD Manual Pages


home | help
LISTXATTR(2)			 System	calls			  LISTXATTR(2)

       listxattr, llistxattr, flistxattr - list	extended attribute names

       #include	<sys/types.h>
       #include	<attr/xattr.h>

       ssize_t listxattr (const	char *path,
			    char *list,	size_t size);
       ssize_t llistxattr (const char *path,
			    char *list,	size_t size);
       ssize_t flistxattr (int filedes,
			    char *list,	size_t size);

       Extended	attributes are name:value pairs	associated with	inodes (files,
       directories, symlinks, etc).  They are extensions  to  the  normal  at-
       tributes	 which	are associated with all	inodes in the system (i.e. the
       stat(2) data).  A complete overview of extended attributes concepts can
       be found	in attr(5).

       listxattr  retrieves  the  list	of extended attribute names associated
       with the	given path in the filesystem.  The list	is the set  of	(NULL-
       terminated)  names,  one	after the other.  Names	of extended attributes
       to which	the calling process does not have access may be	 omitted  from
       the list.  The length of	the attribute name list	is returned.

       llistxattr  is identical	to listxattr, except in	the case of a symbolic
       link, where the list of names of	extended  attributes  associated  with
       the  link itself	is retrieved, not the file that	it refers to.  list is
       a caller-allocated buffer of size size.

       flistxattr is identical to listxattr, only the open file	pointed	to  by
       filedes (as returned by open(2))	is interrogated	in place of path.

       A  single  extended  attribute name is a	simple NULL-terminated string.
       The name	includes a namespace prefix - there may	be  several,  disjoint
       namespaces associated with an individual	inode.

       An  empty  buffer of size zero can be passed into these calls to	return
       the current size	of the list of extended	attribute names, which can  be
       used  to	 estimate  the size of a buffer	which is sufficiently large to
       hold the	list of	names.

       The list	of names is returned as	an unordered array of  NULL-terminated
       character  strings  (attribute names are	separated by NULL characters),
       like this:

       Filesystems like	ext2, ext3 and XFS which implement  POSIX  ACLs	 using
       extended	attributes, might return a list	like this:

       On  success,  a	positive number	is returned indicating the size	of the
       extended	attribute name list.  On failure, -1 is	returned and errno  is
       set appropriately.

       If  the	size of	the list buffer	is too small to	hold the result, errno
       is set to ERANGE.

       If extended attributes are not supported	by the filesystem, or are dis-
       abled, errno is set to ENOTSUP.

       The  errors  documented for the stat(2) system call are also applicable

       Andreas Gruenbacher, <>	and the	SGI XFS	devel-
       opment  team,  <>.	Please send any	bug reports or
       comments	to these addresses.

       getfattr(1), setfattr(1), open(2), stat(2),  getxattr(2),  setxattr(2),
       removexattr(2), and attr(5).

Dec 2001		      Extended Attributes		  LISTXATTR(2)


Want to link to this manual page? Use this URL:

home | help