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

FreeBSD Manual Pages


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

       getxattr, lgetxattr, fgetxattr -	retrieve an extended attribute value

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

       ssize_t getxattr	(const char *path, const char *name,
			    void *value, size_t	size);
       ssize_t lgetxattr (const	char *path, const char *name,
			    void *value, size_t	size);
       ssize_t fgetxattr (int filedes, const char *name,
			    void *value, 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).

       getxattr	 retrieves  the	 value of the extended attribute identified by
       name and	associated with	the given path in the filesystem.  The	length
       of the attribute	value is returned.

       lgetxattr  is  identical	 to getxattr, except in	the case of a symbolic
       link, where the link itself is  interrogated,  not  the	file  that  it
       refers to.

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

       An extended attribute name is a	simple	NULL-terminated	 string.   The
       name includes a namespace prefix	- there	may be several,	disjoint name-
       spaces associated with an individual inode.  The	value of  an  extended
       attribute  is  a	chunk of arbitrary textual or binary data of specified

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

       The  interface  is  designed to allow guessing of initial buffer	sizes,
       and to enlarge buffers when the return value indicates that the	buffer
       provided	was too	small.

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

       If  the named attribute does not	exist, or the process has no access to
       this attribute, errno is	set to ENOATTR.

       If the size of the value	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), setxattr(2), listxattr(2),
       removexattr(2), and attr(5).

Dec 2001		      Extended Attributes		   GETXATTR(2)


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

home | help