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

Revision 1.2, Thu Jan 25 19:55:30 2001 UTC (16 years, 8 months ago) by xfs
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +200 -120 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>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#DIAGNOSTICS">DIAGNOSTICS</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_multi, attr_multif - manipulate multiple user attributes on a filesystem object at once</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_multi (const char</B></font> <font size=3>*</font><font size=3><B>path, attr_multiop_t</B></font> <font size=3>*</font><font size=3><B>oplist,</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>int count, int flags);</B></font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3><B>int attr_multif (int fd, attr_multiop_t</B></font> <font size=3>*</font><font size=3><B>oplist,</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="26%">
</p>
</td>
<td valign="top" align="left" width="73%">
<p><font size=3><B>int count, int flags);</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_multi</I></font> <font size=3>and</font> <font size=3><I>attr_multif</I></font> <font size=3>functions provide a way to operate on multiple attributes of a filesystem object at once.</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>oplist</I></font> <font size=3>is an array of</font> <font size=3><EM>attr_multiop_t</EM></font> <font size=3>structures. Each element in that array describes a single attribute operation and provides all the information required to carry out that operation and to check for success or failure of that operation.</font> <font size=3><I>Count</I></font> <font size=3>tells how many elements are in the</font> <font size=3><I>oplist</I></font> <font size=3>array.</font></p>
<p style="margin-left: 18%"><font size=3>The contents of an</font> <font size=3><EM>attr_multiop_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>int am_opcode; /* which operation to perform (see below) */</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>int am_error; /* [out arg] result of this sub&shy;op (an errno) */</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 *am_attrname; /* attribute name to work with */</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 *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */</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>int am_length; /* [in/out arg] length of value */</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>int am_flags; /* flags (bit&shy;wise OR of #defines below) */</EM></font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>am_opcode</I></font> <font size=3>field defines how the remaining fields are to be interpreted and can take on one of the following values:</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>ATTR_OP_GET /* return the indicated attr's value */</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>ATTR_OP_SET /* set/create the indicated attr/value pair */</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>ATTR_OP_REMOVE /* remove the indicated attr */</EM></font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>am_error</I></font> <font size=3>field will contain the appropriate error result code if that sub&shy;operation fails. The result codes for a given sub&shy;operation are a subset of the result codes that are possible from the corresponding single&shy;attribute function call. For example, the result code possible from an</font> <font size=3><EM>ATTR_OP_GET</EM></font> <font size=3>sub&shy;operation are a subset of those that can be returned from an</font> <font size=3><I>attr_get</I></font> <font size=3>function call.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>am_attrname</I></font> <font size=3>field is a pointer to a NULL terminated string giving the attribute name that the sub&shy;operation should operate on.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>am_attrvalue, am_length</I></font> <font size=3>and</font> <font size=3><I>am_flags</I></font> <font size=3>fields are used to store the value of the named attribute, and some control flags for that sub&shy;operation, respectively. Their use varies depending on the value of the</font> <font size=3><I>am_opcode</I></font> <font size=3>field.</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><B>ATTR_OP_GET ATTR_OP_SET</B></font></p>
</td>
<td valign="top" align="left" width="63%">
<p><font size=3>The</font> <font size=3><I>am_attrvalue</I></font> <font size=3>field is a pointer to a empty buffer that will be overwritten with the value of the named attribute. The</font> <font size=3><I>am_length</I></font> <font size=3>field is initially the total size of the memory buffer that the</font> <font size=3><I>am_attrvalue</I></font> <font size=3>field points to. After the operation, the</font> <font size=3><I>am_length</I></font> <font size=3>field contains the actual size of the attribute&acute;s value. The</font> <font size=3><I>am_flags</I></font> <font size=3>field may be set to the</font> <font size=3><EM>ATTR_ROOT</EM></font> <font size=3>flag. If the process has appropriate priviledges, the ROOT namespace will be searched for the named attribute, otherwise the USER namespace will be searched.</font></p>
<p><font size=3>The</font> <font size=3><I>am_attrvalue</I></font> <font size=3>and</font> <font size=3><I>am_length</I></font> <font size=3>fields contain the new value for the given attribute name and its length. The</font> <font size=3><EM>ATTR_ROOT</EM></font> <font size=3>flag may be set in the</font> <font size=3><I>am_flags</I></font> <font size=3>field. If the process has appropriate priviledges, the ROOT namespace will be searched for the named attribute, otherwise the USER namespace will be searched. The</font> <font size=3><EM>ATTR_CREATE</EM></font> <font size=3>and the</font> <font size=3><EM>ATTR_REPLACE</EM></font> <font size=3>flags may also be set in the</font> <font size=3><I>am_flags</I></font> <font size=3>field (but not simultaneously). If the</font> <font size=3><EM>ATTR_CREATE</EM></font> <font size=3>flag is set, the sub&shy;operation will set the</font> <font size=3><I>am_error</I></font> <font size=3>field to EEXIST if the named attribute already exists. If the</font> <font size=3><EM>ATTR_REPLACE</EM></font> <font size=3>flag is set, the sub&shy;operation will set the</font> <font size=3><I>am_error</I></font> <font size=3>field to ENOATTR if the named attribute does not already</font></p>
</td>
</tr>
</table>
<br>
</p>

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

<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="36%">
</td>
<td valign="top" align="left" width="63%">
<p><font size=3>exist. If neither of those two flags are set and the attribute does not exist, then the attribute will be created with the given value. If neither of those two flags are set and the attribute already exists, then the value will be replaced with the given value.</font></p>
</td>
</tr>
</table>

<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%">
</td>
<td valign="top" align="left" width="18%">
<p><font size=2><B>ATTR_OP_REMOVE</B></font></p>
</td>
<td valign="top" align="left" width="63%">
<p><font size=3>The</font> <font size=3><I>am_attrvalue</I></font> <font size=3>and</font> <font size=3><I>am_length</I></font> <font size=3>fields are not used and are ignored. The</font> <font size=3><I>am_flags</I></font> <font size=3>field may be set to the</font> <font size=3><EM>ATTR_ROOT</EM></font> <font size=3>flag. If the process has appropriate priviledges, the ROOT namespace will be searched for the named attribute, otherwise the USER namespace will be searched.</font></p>
</td>
</tr>
</table>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>flags</I></font> <font size=3>argument to the</font> <font size=3><I>attr_multi</I></font> <font size=3>call is used to control following of symbolic links in the</font> <font size=3><I>path</I></font> <font size=3>argument. The default is to follow symbolic links,</font> <font size=3><I>flags</I></font> <font size=3>should be set to ATTR_DONTFOLLOW to not follow symbolic links.</font></p>
<p style="margin-left: 18%"><font size=3><I>attr_multi</I></font> <font size=3>will fail if one or more of the following are true:</font>
<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%">
</p>
</td>
<td valign="top" align="left" width="8%">
<p><font size=2>[ENOENT]</font></p>
<p><font size=2>[EPERM]</font></p>
<p><font size=2>[ENOTDIR] [EACCES]</font></p>
<p><font size=2>[EINVAL]</font></p>
<p><font size=2>[EFAULT]</font></p>
<p><font size=2>[ELOOP]</font></p>
</td>
<td valign="top" align="left" width="6%">
</td>
<td valign="top" align="left" width="65%">
<p><font size=3>The named file does not exist.</font></p>
<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> <font size=2>ID</font> <font size=3>is not super&shy;user.</font></p>
<p><font size=3>A component of the path prefix is not a directory.</font></p>
<p><font size=3>Search permission is denied on a component of the path prefix.</font></p>
<p><font size=3>A bit other than ATTR_DONTFOLLOW was set in the</font> <font size=3><I>flag</I></font> <font size=3>argument.</font></p>
<p><font size=3><I>Path,</I></font> <font size=3>or</font> <font size=3><I>oplist</I></font> <font size=3>points outside the allocated address space of the process.</font></p>
<p><font size=3>A path name lookup involved too many symbolic links.</font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=2>[ENAMETOOLONG]</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="34%">
</p>
</td>
<td valign="top" align="left" width="65%">
<p><font size=3>The length of</font> <font size=3><I>path</I></font> <font size=3>exceeds</font> <font size=2>{</font><font size=2><I>MAXPATHLEN</I></font><font size=2>},</font> <font size=3>or a pathname component is longer than</font> <font size=2>{</font><font size=2><I>MAXNAMELEN</I></font><font size=2>}.</font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=3><I>attr_multif</I></font> <font size=3>will fail if:</font>
<table width="98%" rules="none" frame="none" cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="18%">
</p>
</td>
<td valign="top" align="left" width="8%">
<p><font size=2>[EINVAL]</font></p>
<p><font size=2>[EFAULT] [EBADF]</font></p>
</td>
<td valign="top" align="left" width="5%">
</td>
<td valign="top" align="left" width="59%">
<p><font size=3>A bit was set in the</font> <font size=3><I>flag</I></font> <font size=3>argument, or</font> <font size=3><I>fd</I></font> <font size=3>refers to a socket, not a file.</font></p>
<p><font size=3><I>Oplist</I></font> <font size=3>points outside the allocated address space of the process.</font></p>
<p><font size=3><I>Fd</I></font> <font size=3>does not refer to a valid descriptor.</font></p>
</td>
<td valign="top" align="left" width="8%">
</td>
</tr>
</table>
</p>
<a name="SEE ALSO"></a><h2>SEE ALSO</h2><p style="margin-left: 18%"><font size=3>attr(1),<br>
attrctl(2),<br>
attr_get(3), attr_getf(3),<br>
attr_list(3), attr_list(3)<br>
attr_remove(3), attr_removef(3),<br>
attr_set(3), attr_set(3)</font></p>
<a name="DIAGNOSTICS"></a><h2>DIAGNOSTICS</h2><p style="margin-left: 18%"><font size=3>Upon successful completion of the</font> <font size=3><I>attr_multi</I></font> <font size=3>call, a value of 0 is returned. Otherwise, a value of -1 is returned and</font> <font size=3><I>errno</I></font> <font size=3>is set to indicate the error. Note that the individual operations listed in the</font> <font size=3><I>oplist</I></font> <font size=3>array each have their own error return fields. The</font> <font size=3><I>errno</I></font> <font size=3>variable only records the result of the</font> <font size=3><I>attr_multi</I></font> <font size=3>call itself, not the result of any of the sub&shy;operations.</font><br>
</p>
</body>
</html>