[BACK]Return to attr_list.html CVS log [TXT][DIR] Up to [Development] / xfs-website.orig / manpages
File: [Development] / xfs-website.orig / manpages / attr_list.html (download) (as text)

Revision 1.1, Wed Sep 27 05:01:46 2000 UTC (17 years, 1 month ago) by xfs
Branch: MAIN 

Update manpages.
These changes from Martin Peterson.

<html>
<head>
<meta name="Content-Style" content="text/css">
</head>
<body>
<a href="#NAME">NAME</a><br>
<a href="#C SYNOPSIS">C SYNOPSIS</a><br>
<a href="##include <sys/attributes.h>">#include <sys/attributes.h></a><br>
<a href="#OVERVIEW">OVERVIEW</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
<!-- Creator     : groff version 1.15  -->
<!-- CreationDate: Tue Sep 26 23:59:39 2000
 -->
<!-- Total number of pages: 2 -->
<!-- Page: 1 -->
<!-- left  margin: 100 -->
<!-- right margin: 750 -->
<a name="NAME"></a><h2>NAME</h2><p><font size=3>attr_list, attr_listf - list the names of the user attributes of a filesystem object</p>
<a name="C SYNOPSIS"></a><h2>C SYNOPSIS</h2><a name="#include <sys/attributes.h>"></a><h2>#include <sys/attributes.h></h2><p><font size=3><B>int attr_list (const char</B> <font size=3>*<font size=3><B>path, char</B> <font size=3>*<font size=3><B>buffer,<br>
<span style=" text-indent: 0.4500in;"></span>const int buffersize, int flags,<br>
<span style=" text-indent: 0.4500in;"></span>attrlist_cursor_t</B> <font size=3>*<font size=3><B>cursor);</p>
</B><p><font size=3><B>int attr_listf (int fd, char</B> <font size=3>*<font size=3><B>buffer,<br>
<span style=" text-indent: 0.4800in;"></span>const int buffersize, int flags,<br>
<span style=" text-indent: 0.4800in;"></span>attrlist_cursor_t</B> <font size=3>*<font size=3><B>cursor);</p>
</B><a name="OVERVIEW"></a><h2>OVERVIEW</h2><p><font size=3>The <font size=3><I>attr</I> <font size=3>group of system calls implement the ability for a user to attach name/value pairs to objects within the filesystem.</p>
<p><font size=3>They could be used to store meta-information about the file. For example "character-set=kanji" could tell a docu- ment 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.</p>
<p><font size=3>The <font size=3><I>names</I> <font size=3>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.</p>
<p><font size=3>The <font size=3><I>values</I> <font size=3>can be up to ATTR_MAX_VALUELEN (currently 64KB) of arbitrary binary data.</p>
<p><font size=3>Attributes can be attached to all types of inodes: regular files, directories, symbolic links, device nodes, etc.</p>
<p><font size=3>There are 2 disjoint attribute name spaces associated with every filesystem object. They are the <font size=3><B>root</B> <font size=3>and <font size=3><B>user</B> <font size=3>address spaces. The <font size=3><B>root</B> <font size=3>address space is accessable only to the super-user, and then only by specifying a flag argument to the function call. Other users will not see or be able to modify attributes in the <font size=3><B>root</B> <font size=3>address space. The <font size=3><B>user</B> <font size=3>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.</p>
<p><font size=3>Attributes are currently supported only in the XFS filesystem type.</p>
<a name="DESCRIPTION"></a><h2>DESCRIPTION</h2><p><font size=3>The <font size=3><I>attr_list</I> <font size=3>and <font size=3><I>attr_listf</I> <font size=3>functions provide a way to list the existing attributes of a filesystem object.</p>
<p><font size=3><I>Path</I> <font size=3>points to a path name for a filesystem object, and <font size=3><I>fd</I> <font size=3>refers to the file descriptor associated with a file. The <font size=3><I>buffer</I> <font size=3>will be filled with a structure describing at least a portion of the attributes associated with the given filesys- tem object. <font size=3><I>Buffer</I> <font size=3>will be overwritten with an <font size=3><EM>attrlist_t</EM> <font size=3>structure containing a list of the attributes associated with that filesystem object, up to a maximum of <font size=3><I>buffersize</I> <font size=3>bytes. The <font size=3><I>buffer</I> <font size=3>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.</p>
<p><font size=3>The contents of an <font size=3><EM>attrlist_t</EM> <font size=3>structure include the following members:</p>
<p><span style=" text-indent: 0.1800in;"></span><font size=3><EM>__int32_t al_count; /</EM><font size=3>* <font size=3><EM>number of entries in attrlist</EM> <font size=3>*<font size=3><EM>/<br>
<span style=" text-indent: 0.1800in;"></span>__int32_t al_more; /</EM><font size=3>* <font size=3><EM>T/F: more attrs (do syscall again)</EM> <font size=3>*<font size=3><EM>/<br>
<span style=" text-indent: 0.1800in;"></span>__int32_t al_offset[1]; /</EM><font size=3>* <font size=3><EM>byte offsets of attrs [var-sized]</EM> <font size=3>*<font size=3><EM>/</p>
</EM><p><font size=3>The <font size=3><I>al_count</I> <font size=3>field shows the number of attributes represented in this buffer, which is also the number of elements in the <font size=3><I>al_offset</I> <font size=3>array. The <font size=3><I>al_more</I> <font size=3>field will be non-zero if another <font size=3><I>attr_list</I> <font size=3>call would result in more attributes. The <font size=3><I>al_offset</I> <font size=3>array contains the byte offset within the <font size=3><I>buffer</I> <font size=3>of the structure describing each of the attributes, an <font size=3><EM>attrlist_ent_t</EM> <font size=3>structure. The <font size=3><EM>ATTR_ENTRY(buffer, index)</EM> <font size=3>macro will help with decoding the list. It takes a pointer to the <font size=3><I>buffer</I> <font size=3>and an <font size=3><I>index</I> <font size=3>into the <font size=3><I>al_offset</I> <font size=3>array and returns a pointer to the corresponding <font size=3><EM>attrlist_ent_t</EM> <font size=3>structure.</p>
<p><font size=3>The contents of an <font size=3><EM>attrlist_ent_t</EM> <font size=3>structure include the following members:</p>
<p><span style=" text-indent: 0.1800in;"></span><font size=3><EM>u_int32_t a_valuelen; /</EM><font size=3>* <font size=3><EM>number bytes in value of attr</EM> <font size=3>*<font size=3><EM>/<br>
<span style=" text-indent: 0.1800in;"></span>char a_name[]; /</EM><font size=3>* <font size=3><EM>attr name (NULL terminated)</EM> <font size=3>*<font size=3><EM>/</p>
</EM><p><font size=3>The <font size=3><I>a_valuelen</I> <font size=3>field shows the size in bytes of the value associated with the attribute whose name is stored in the <font size=3><I>a_name</I> <font size=3>field. The name is a NULL terminated string.</p>
<p><font size=3>Note that the value of the attribute cannot be obtained through this interface, the <font size=3><I>attr_get</I> <font size=3>call should be used to get the value. The <font size=3><I>attr_list</I> <font size=3>interface tells the calling process how large of a buffer it must have in order to get the attribute´s value.</p>
<p><font size=3>The <font size=3><I>flags</I> <font size=3>argument can contain the following symbols bitwise OR´ed together:<br>
</p>

<!-- Page: 2  -->
<!-- left  margin: 100 -->
<!-- right margin: 750 -->

<table width="100%"  rules="none"  frame="none"  cols="3">
<tr valign="top" align="left">
<td valign="top" align="left"  width="17.5385%">
<p><font size=2>ATTR_ROOT</p>
</td>
<td valign="top" align="left"  width="2.4615%">
</td>
<td valign="top" align="left"  width="80.0000%">
<p><font size=3>List the attributes that are in the <font size=3><B>root</B> <font size=3>address space, not in the <font size=3><B>user</B> <font size=3>address space. (limited to use by super-user only)</p>
</td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="17.5385%">
<p><font size=2>ATTR_DONTFOLLOW</p>
</td>
<td valign="top" align="left"  width="2.4615%">
</td>
<td valign="top" align="left"  width="80.0000%">
<p><font size=3>Do not follow symbolic links when resolving a <font size=3><I>path</I> <font size=3>on an <font size=3><I>attr_list</I> <font size=3>function call. The default<br>
is to follow symbolic links.</p>
</td>
</tr>
</table>
<p><font size=3>The <font size=3><I>cursor</I> <font size=3>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 <font size=3><I>cursor</I> <font size=3>are to pass it into an <font size=3><I>attr_list</I> <font size=3>function call or to zero it out. It should be zero´ed out before the first <font size=3><I>attr_list</I> <font size=3>call. Note that multi-threaded applications may keep more than one <font size=3><I>cursor</I> <font size=3>in order to serve multiple contexts, ie: the <font size=3><I>attr_list</I> <font size=3>call is "thread-safe".</p>
<p><font size=3><I>attr_list</I> <font size=3>will fail if one or more of the following are true:</p>

<table width="100%"  rules="none"  frame="none"  cols="3">
<tr valign="top" align="left">
<td valign="top" align="left"  width="8.9231%">
<p><font size=2>[ENOENT]</p>
<p><font size=2>[EPERM]</p>
<p><font size=2>[ENOTDIR]</p>
<p><font size=2>[EACCES]</p>
<p><font size=2>[EINVAL]</p>
<p><font size=2>[EFAULT]</p>
<p><font size=2>[ELOOP]</p>
</td>
<td valign="top" align="left"  width="6.7692%">
</td>
<td valign="top" align="left"  width="84.3077%">
<p><font size=3>The named file does not exist.</p>
<p><font size=3>The effective user <sub>ID</sub> does not match the owner of the file and the effective user <sub>ID</sub> is not super- user.</p>
<p><font size=3>A component of the path prefix is not a directory.</p>
<p><font size=3>Search permission is denied on a component of the path prefix.</p>
<p><font size=3>A bit was set in the <font size=3><I>flag</I> <font size=3>argument that is not defined for this system call, or the buffer was too small or too large.</p>
<p><font size=3>Either <font size=3><I>Path</I> <font size=3>or <font size=3><I>buffer</I> <font size=3>points outside the allocated address space of the process, or <font size=3><I>buffer</I> <font size=3>or <font size=3><I>buf- size</I> <font size=3>are not 32bit aligned.</p>
<p><font size=3>A path name lookup involved too many symbolic links.</p>
</td>
</tr>
</table>
<br>
<p><font size=2>[ENAMETOOLONG]</p>

<table width="100%"  rules="none"  frame="none"  cols="2">
<tr valign="top" align="left">
<td valign="top" align="left"  width="15.6923%">
</td>
<td valign="top" align="left"  width="84.3077%">
<p><font size=3>The length of <font size=3><I>path</I> <font size=3>exceeds</p>
</td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="15.6923%">
</td>
<td valign="top" align="left"  width="84.3077%">
<p><font size=2><span style=" text-indent: 1.5800in;"></span>{<font size=2><I>MAXPATHLEN</I><font size=2>}, <font size=3>or a pathname component is longer than <sub>{</sub><font size=3><I><sub>MAXNAME-</sub></p>
</I></td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="15.6923%">
</td>
<td valign="top" align="left"  width="84.3077%">
<p><font size=2><I>LEN</I><font size=2>}.</p>
</td>
</tr>
</table>
<br>
<p><font size=2>[ENOATTR] <font size=3><I>attribute</I> <font size=3>does not exist for this file.</p>
<p><font size=3><I>attr_listf</I> <font size=3>will fail if:</p>

<table width="100%"  rules="none"  frame="none"  cols="3">
<tr valign="top" align="left">
<td valign="top" align="left"  width="8.0000%">
<p><font size=2>[EINVAL]</p>
<p><font size=2>[EFAULT]</p>
<p><font size=2>[EBADF]</p>
</td>
<td valign="top" align="left"  width="5.8462%">
</td>
<td valign="top" align="left"  width="86.1538%">
<p><font size=3>A bit was set in the <font size=3><I>flag</I> <font size=3>argument that is not defined for this system call, or <font size=3><I>fd</I> <font size=3>refers to a socket, not a file, or the buffer was too small or too large.</p>
<p><font size=3>Either <font size=3><I>Path</I> <font size=3>or <font size=3><I>buffer</I> <font size=3>points outside the allocated address space of the process, or <font size=3><I>buffer</I> <font size=3>or <font size=3><I>buf- size</I> <font size=3>are not 32bit aligned.</p>
<p><font size=3><I>Fd</I> <font size=3>does not refer to a valid descriptor.</p>
</td>
</tr>
</table>
<br>
<a name="SEE ALSO"></a><h2>SEE ALSO</h2>
<table width="100%"  rules="none"  frame="none"  cols="2">
<tr valign="top" align="left">
<td valign="top" align="left"  width="29.3846%">
<p><font size=3>attr(1),<br>
attr_get(2), attr_getf(2),<br>
attr_multi(2), attr_multif(2)<br>
attr_remove(2), attr_removef(2),<br>
attr_set(2), attr_set(2)</p>
</td>
<td valign="top" align="left"  width="70.6154%">
</td>
</tr>
</table>
<br>
<a name="DIAGNOSTICS"></a><h2>DIAGNOSTICS</h2><p><font size=3>Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and <font size=3><I>errno</I> <font size=3>is set to indi- cate the error.<br>
</p>
</body>
</html>