[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.2, Thu Jan 25 19:55:30 2001 UTC (16 years, 9 months ago) by xfs
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +122 -111 lines 

Man pages update.

<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 &lt;sys/attributes.h&gt;">#include &lt;sys/attributes.h&gt;</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<!-- Creator     : groff version 1.16.1  -->
<!-- CreationDate: Wed Jan 24 01:42:49 2001
 -->
<!-- Total number of pages: 2 -->
<!-- Page: 1 -->
<!-- left  margin: 220 -->
<!-- right margin: 750 -->
<a name="NAME"></a><h2>NAME</h2><p style="margin-left: 18%"><font size=3>attr_list, attr_listf - list the names of the user attributes of a filesystem object</font></p>
<a name="C SYNOPSIS"></a><h2>C SYNOPSIS</h2><a name="#include &lt;sys/attributes.h&gt;"></a><h2>#include &lt;sys/attributes.h&gt;</h2><p style="margin-left: 18%"><font size=3><B>int attr_list (const char</B></font> <font size=3>*</font><font size=3><B>path, char</B></font> <font size=3>*</font><font size=3><B>buffer,</B></font>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="25%">
</p>
</td>
<td valign="top" align="left" width="74%">
<p><font size=3><B>const int buffersize, int flags,</B></font></p>
</td>
</tr>
</table>

<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="25%">
</p>
</td>
<td valign="top" align="left" width="74%">
<p><font size=3><B>attrlist_cursor_t</B></font> <font size=3>*</font><font size=3><B>cursor);</B></font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3><B>int attr_listf (int fd, char</B></font> <font size=3>*</font><font size=3><B>buffer,</B></font>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="25%">
</p>
</td>
<td valign="top" align="left" width="74%">
<p><font size=3><B>const int buffersize, int flags,</B></font></p>
</td>
</tr>
</table>

<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="25%">
</p>
</td>
<td valign="top" align="left" width="74%">
<p><font size=3><B>attrlist_cursor_t</B></font> <font size=3>*</font><font size=3><B>cursor);</B></font></p>
</td>
</tr>
</table>
</p>
<a name="DESCRIPTION"></a><h2>DESCRIPTION</h2><p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>attr_list</I></font> <font size=3>and</font> <font size=3><I>attr_listf</I></font> <font size=3>functions provide a way to list the existing attributes of a filesystem object.</font></p>
<p style="margin-left: 18%"><font size=3><I>Path</I></font> <font size=3>points to a path name for a filesystem object, and</font> <font size=3><I>fd</I></font> <font size=3>refers to the file descriptor associated with a file. The</font> <font size=3><I>buffer</I></font> <font size=3>will be filled with a structure describing at least a portion of the attributes associated with the given filesystem object.</font> <font size=3><I>Buffer</I></font> <font size=3>will be overwritten with an</font> <font size=3><EM>attrlist_t</EM></font> <font size=3>structure containing a list of the attributes associated with that filesystem object, up to a maximum of</font> <font size=3><I>buffersize</I></font> <font size=3>bytes. The</font> <font size=3><I>buffer</I></font> <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.</font></p>
<p style="margin-left: 18%"><font size=3>The contents of an</font> <font size=3><EM>attrlist_t</EM></font> <font size=3>structure include the following members:</font>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="21%">
</p>
</td>
<td valign="top" align="left" width="78%">
<p><font size=3><EM>__int32_t al_count; /</EM></font><font size=3>*</font> <font size=3><EM>number of entries in attrlist</EM></font> <font size=3>*</font><font size=3><EM>/</EM></font></p>
</td>
</tr>
</table>

<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="21%">
</p>
</td>
<td valign="top" align="left" width="78%">
<p><font size=3><EM>__int32_t al_more; /</EM></font><font size=3>*</font> <font size=3><EM>T/F: more attrs (do syscall again)</EM></font> <font size=3>*</font><font size=3><EM>/</EM></font></p>
</td>
</tr>
</table>

<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="21%">
</p>
</td>
<td valign="top" align="left" width="78%">
<p><font size=3><EM>__int32_t al_offset[1]; /</EM></font><font size=3>*</font> <font size=3><EM>byte offsets of attrs [var&shy;sized]</EM></font> <font size=3>*</font><font size=3><EM>/</EM></font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>al_count</I></font> <font size=3>field shows the number of attributes represented in this buffer, which is also the number of elements in the</font> <font size=3><I>al_offset</I></font> <font size=3>array. The</font> <font size=3><I>al_more</I></font> <font size=3>field will be non&shy;zero if another</font> <font size=3><I>attr_list</I></font> <font size=3>call would result in more attributes. The</font> <font size=3><I>al_offset</I></font> <font size=3>array contains the byte offset within the</font> <font size=3><I>buffer</I></font> <font size=3>of the structure describing each of the attributes, an</font> <font size=3><EM>attrlist_ent_t</EM></font> <font size=3>structure. The</font> <font size=3><EM>ATTR_ENTRY(buffer, index)</EM></font> <font size=3>macro will help with decoding the list. It takes a pointer to the</font> <font size=3><I>buffer</I></font> <font size=3>and an</font> <font size=3><I>index</I></font> <font size=3>into the</font> <font size=3><I>al_offset</I></font> <font size=3>array and returns a pointer to the corresponding</font> <font size=3><EM>attrlist_ent_t</EM></font> <font size=3>structure.</font></p>
<p style="margin-left: 18%"><font size=3>The contents of an</font> <font size=3><EM>attrlist_ent_t</EM></font> <font size=3>structure include the following members:</font>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="21%">
</p>
</td>
<td valign="top" align="left" width="78%">
<p><font size=3><EM>u_int32_t a_valuelen; /</EM></font><font size=3>*</font> <font size=3><EM>number bytes in value of attr</EM></font> <font size=3>*</font><font size=3><EM>/</EM></font></p>
</td>
</tr>
</table>

<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="21%">
</p>
</td>
<td valign="top" align="left" width="78%">
<p><font size=3><EM>char a_name[]; /</EM></font><font size=3>*</font> <font size=3><EM>attr name (NULL terminated)</EM></font> <font size=3>*</font><font size=3><EM>/</EM></font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>a_valuelen</I></font> <font size=3>field shows the size in bytes of the value associated with the attribute whose name is stored in the</font> <font size=3><I>a_name</I></font> <font size=3>field. The name is a NULL terminated string.</font></p>
<p style="margin-left: 18%"><font size=3>Note that the value of the attribute cannot be obtained through this interface, the</font> <font size=3><I>attr_get</I></font> <font size=3>call should be used to get the value. The</font> <font size=3><I>attr_list</I></font> <font size=3>interface tells the calling process how large of a buffer it must have in order to get the attribute&acute;s value.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>flags</I></font> <font size=3>argument can contain the following symbols bitwise OR&eacute;d together:</font>
<table width="99%" rules="none" frame="none" cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="18%">
</p>
</td>
<td valign="top" align="left" width="18%">
<p><font size=2>ATTR_ROOT</font></p>
<p><font size=2>ATTR_DONTFOLLOW</font></p>
</td>
<td valign="top" align="left" width="63%">
<p><font size=3>List the attributes that are in the</font> <font size=3><B>root</B></font> <font size=3>address space, not in the</font> <font size=3><B>user</B></font> <font size=3>address space. (limited to use by super&shy;user only)</font></p>
<p><font size=3>Do not follow symbolic links when resolving a</font> <font size=3><I>path</I></font> <font size=3>on an</font> <font size=3><I>attr_list</I></font> <font size=3>function call. The default is to follow symbolic links.</font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>cursor</I></font> <font size=3>argument is a pointer to an opaque data structure that the kernel uses to track the calling process&acute;s position in the attribute list. The only valid operations on a</font> <font size=3><I>cursor</I></font> <font size=3>are to pass it into an</font> <font size=3><I>attr_list</I></font> <font size=3>function call or to zero it out. It should be zero&eacute;d out before the first</font> <font size=3><I>attr_list</I></font> <font size=3>call. Note that multi&shy;threaded applications may keep more than one</font> <font size=3><I>cursor</I></font> <font size=3>in order to serve multiple contexts, ie: the</font> <font size=3><I>attr_list</I></font> <font size=3>call is &quot;thread&shy;safe&quot;.</font></p>
<p style="margin-left: 18%"><font size=3><I>attr_list</I></font> <font size=3>will fail if one or more of the following are true:</font></p>
<p style="margin-left: 18%"><font size=2>[ENOENT]</font> <font size=3>The named file does not exist.</font>
<table width="98%" rules="none" frame="none" cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="18%">
</p>
</td>
<td valign="top" align="left" width="15%">
<p><font size=2>[EPERM]</font></p>
</td>
<td valign="top" align="left" width="65%">
<p><font size=3>The effective user</font> <font size=2>ID</font> <font size=3>does not match the owner of the file and the effective user</font></p>
</td>
</tr>
</table>
<font size=2> ID</font> <font size=3>is not super&shy;user.</font><br>
</p>

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

<table width="97%" rules="none" frame="none" cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="18%">
</td>
<td valign="top" align="left" width="8%">
</td>
<td valign="top" align="left" width="6%">
</td>
<td valign="top" align="left" width="65%">
</td>
</tr>
</table>
<br></body>
</html>