ATTR_GET(2)							   ATTR_GET(2)

NAME    [Toc]    [Back]

     attr_get, attr_getf - get the value of a user attribute of	a filesystem
     object

C SYNOPSIS    [Toc]    [Back]

     #include <sys/attributes.h>

     int attr_get (const char *path, const char	*attrname,
		   char	*attrvalue, int	*valuelength, int flags);

     int attr_getf (int	fd, const char *attrname,
		    char *attrvalue, int *valuelength, int flags);

OVERVIEW    [Toc]    [Back]

     The attr group of system calls implement the ability for a	user to	attach
     name/value	pairs to objects within	the filesystem.

     They could	be used	to store meta-information about	the file.  For example
     "character-set=kanji" could tell a	document browser to use	the Kanji
     character set when	displaying that	document and "thumbnail=..." could
     provide a reduced resolution overview of a	high resolution	graphic	image.

     The names can be up to MAXNAMELEN bytes in	length,	terminated by the
     first 0 byte.  The	intent is that they be printable ASCII (or other
     character set) names for the attribute.

     The values	can be up to ATTR_MAX_VALUELEN (currently 64KB)	of arbitrary
     binary data.

     Attributes	can be attached	to all types of	inodes:	 regular files,
     directories, symbolic links, device nodes,	etc.

     There are 2 disjoint attribute name spaces	associated with	every
     filesystem	object.	 They are the root and user address spaces.  The root
     address space is accessible only to privileged users, and only then by
     specifying	a flag argument	to the function	call.  A privileged user can
     be	either the superuser in	an IRIX	environment, or	a user with
     CAP_DEVICE_MGT capability.	 Other users will not see or be	able to	modify
     attributes	in the root address space.  The	user address space is
     protected by the normal file permissions mechanism, so the	owner of the
     file can decide who is able to see	and/or modify the value	of attributes
     on	any particular file.

     Attributes	are currently fully supported only in the XFS and CXFS
     filesystem	types.	Other filesystem types may provide a partial
     implementation.

DESCRIPTION    [Toc]    [Back]

     The attr_get and attr_getf	functions provide a way	to retrieve the	value
     of	an attribute.





									Page 1






ATTR_GET(2)							   ATTR_GET(2)



     Path points to a path name	for a filesystem object, and fd	refers to the
     file descriptor associated	with a file.  If the attribute attrname
     exists, the value associated with it will be copied into the attrvalue
     buffer.  The valuelength argument is an input/output argument that	on the
     call to attr_get should contain the maximum size of attribute value the
     process is	willing	to accept.  On return, the valuelength will have been
     modified to show the actual size of the attribute value returned.	The
     flags argument can	contain	the following symbols bitwise OR'ed together:

     ATTR_ROOT
	  Look for attrname in the root	address	space, not in the user address
	  space.  (limited to use by super-user	only)

     ATTR_DONTFOLLOW
	  Do not follow	symbolic links when resolving a	path on	an attr_get
	  function call.  The default is to follow symbolic links.

     attr_get will fail	if one or more of the following	are true:

     [ENOATTR]	      The attribute name given is not associated with the
		      indicated	filesystem object.

     [E2BIG]	      The value	of the given attribute is too large to fit
		      into the buffer.	The integer that the valuelength
		      argument points to has been modified to show the actual
		      number of	bytes that would be required to	store the
		      value of that attribute.

     [ENOENT]	      The named	file does not exist.

     [EPERM]	      The effective user ID does not match the owner of	the
		      file and the effective user ID is	not super-user.

     [ENOTDIR]	      A	component of the path prefix is	not a directory.

     [EACCES]	      Search permission	is denied on a component of the	path
		      prefix.

     [EINVAL]	      A	bit was	set in the flag	argument that is not defined
		      for this system call.

     [EFAULT]	      Path, attrname, attrvalue, or valuelength	points outside
		      the allocated address space of the process.

     [ELOOP]	      A	path name lookup involved too many symbolic links.

     [ENAMETOOLONG]   The length of path exceeds {MAXPATHLEN}, or a pathname
		      component	is longer than {MAXNAMELEN}.

     attr_getf will fail if:





									Page 2






ATTR_GET(2)							   ATTR_GET(2)



     [ENOATTR]	    The	attribute name given is	not associated with the
		    indicated filesystem object.

     [E2BIG]	    The	value of the given attribute is	too large to fit into
		    the	buffer.	 The integer that the valuelength argument
		    points to has been modified	to show	the actual number of
		    bytes that would be	required to store the value of that
		    attribute.

     [EINVAL]	    A bit was set in the flag argument that is not defined for
		    this system	call, or fd refers to a	socket,	not a file.

     [EFAULT]	    Attrname, attrvalue, or valuelength	points outside the
		    allocated address space of the process.

     [EBADF]	    Fd does not	refer to a valid descriptor.

SEE ALSO    [Toc]    [Back]

     attr(1),
     attr_list(2), attr_list
     attr_remove(2), attr_removef(2),
     attr_set(2), attr_setf(2),

DIAGNOSTICS    [Toc]    [Back]

     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of	-1 is returned and errno is set	to indicate the	error.


									PPPPaaaaggggeeee 3333