*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> standard/attr_list (2)              



ATTR_LIST(2)							  ATTR_LIST(2)

NAME    [Toc]    [Back]

     attr_list,	attr_listf - list the names of the user	attributes of a
     filesystem	object

C SYNOPSIS    [Toc]    [Back]

     #include <sys/attributes.h>

     int attr_list (const char *path, char *buffer,
		    const int buffersize, int flags,
		    attrlist_cursor_t *cursor);

     int attr_listf (int fd, char *buffer,
		     const int buffersize, int flags,
		     attrlist_cursor_t *cursor);

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

									Page 1

ATTR_LIST(2)							  ATTR_LIST(2)

     The attr_list and attr_listf functions provide a way to list the existing
     attributes	of a filesystem	object.

     Path points to a path name	for a filesystem object, and fd	refers to the
     file descriptor associated	with a file.  The buffer will be filled	with a
     structure describing at least a portion of	the attributes associated with
     the given filesystem object.  Buffer will be overwritten with an
     attrlist_t	structure containing a list of the attributes associated with
     that filesystem object, up	to a maximum of	buffersize bytes.  The buffer
     must be sufficiently large	to hold	the appropriate	data structures	plus
     at	least one maximally sized attribute name, but cannot be	more than
     ATTR_MAX_VALUELEN (currently 64KB)	bytes in length.

     The contents of an	attrlist_t structure include the following members:

	__int32_t al_count; /* number of entries in attrlist */
	__int32_t al_more; /* T/F: more	attrs (do syscall again) */
	__int32_t al_offset[1];	/* byte	offsets	of attrs [var-sized] */

     The al_count field	shows the number of attributes represented in this
     buffer, which is also the number of elements in the al_offset array.  The
     al_more field will	be non-zero if another attr_list call would result in
     more attributes.  The al_offset array contains the	byte offset within the
     buffer of the structure describing	each of	the attributes,	an
     attrlist_ent_t structure.	The ATTR_ENTRY(buffer, index) macro will help
     with decoding the list.  It takes a pointer to the	buffer and an index
     into the al_offset	array and returns a pointer to the corresponding
     attrlist_ent_t structure.

     The contents of an	attrlist_ent_t structure include the following

	u_int32_t a_valuelen; /* number	bytes in value of attr */
	char a_name[]; /* attr name (NULL terminated) */

     The a_valuelen field shows	the size in bytes of the value associated with
     the attribute whose name is stored	in the a_name field.  The name is a
     NULL terminated string.

     Note that the value of the	attribute cannot be obtained through this
     interface,	the attr_get call should be used to get	the value.  The
     attr_list interface tells the calling process how large of	a buffer it
     must have in order	to get the attribute's value.

     The flags argument	can contain the	following symbols bitwise OR'ed

	  List the attributes that are in the root address space, not in the
	  user address space.  (limited	to use by super-user only)

									Page 2

ATTR_LIST(2)							  ATTR_LIST(2)

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

     The cursor	argument is a pointer to an opaque data	structure that the
     kernel uses to track the calling process's	position in the	attribute
     list.  The	only valid operations on a cursor are to pass it into an
     attr_list function	call or	to zero	it out.	 It should be zero'ed out
     before the	first attr_list	call.  Note that multi-threaded	applications
     may keep more than	one cursor in order to serve multiple contexts,	ie:
     the attr_list call	is "thread-safe".

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

     [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

     [EINVAL]	      A	bit was	set in the flag	argument that is not defined
		      for this system call, or the buffer was too small	or too

     [EFAULT]	      Either Path or buffer points outside the allocated
		      address space of the process, or buffer or bufsize are
		      not 32bit	aligned.

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

     [ENOATTR]	      attribute	does not exist for this	file.

     attr_listf	will fail if:

     [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, or
		    the	buffer was too small or	too large.

     [EFAULT]	    Either Path	or buffer points outside the allocated address
		    space of the process, or buffer or bufsize are not 32bit

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

									Page 3

ATTR_LIST(2)							  ATTR_LIST(2)

SEE ALSO    [Toc]    [Back]

     attr_get(2), attr_getf(2),
     attr_multi(2), attr_multi
     attr_set(2), attr_set(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 4444
[ Back ]
 Similar pages
Name OS Title
attr_multi IRIX manipulate multiple user attributes on a filesystem object at once
attr_get IRIX get the value of a user attribute of a filesystem object
attr_set IRIX set the value of a user attribute of a filesystem object
attr_remove IRIX remove a user attribute of a filesystem object
csa_list_calendar_attributes HP-UX list the names of the calendar attributes associated with a calendar
csa_list_entry_attributes HP-UX list the names of the entry attributes associated with the specified entry
sgi_eag_mount IRIX mount a filesystem with attributes
attr IRIX manipulate Extended Attributes on filesystem objects
file IRIX Manipulate file names and attributes
unsharefs IRIX remove a filesystem from the accessable list.
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service