[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.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="#ATTR_OP_GET">ATTR_OP_GET</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_multi, attr_multif - manipulate multiple user attributes on a filesystem object at once</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_multi (const char</B> <font size=3>*<font size=3><B>path, attr_multiop_t</B> <font size=3>*<font size=3><B>oplist,<br>
<span style=" text-indent: 0.4800in;"></span>int count, int flags);</p>
</B><p><font size=3><B>int attr_multif (int fd, attr_multiop_t</B> <font size=3>*<font size=3><B>oplist,<br>
<span style=" text-indent: 0.5100in;"></span>int count, int flags);</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_multi</I> <font size=3>and <font size=3><I>attr_multif</I> <font size=3>functions provide a way to operate on multiple attributes of a filesystem object at once.</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>oplist</I> <font size=3>is an array of <font size=3><EM>attr_multiop_t</EM> <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 oper- ation. <font size=3><I>Count</I> <font size=3>tells how many elements are in the <font size=3><I>oplist</I> <font size=3>array.</p>
<p><font size=3>The contents of an <font size=3><EM>attr_multiop_t</EM> <font size=3>structure include the following members:</p>
<p><span style=" text-indent: 0.1800in;"></span><font size=3><EM>int am_opcode; /* which operation to perform (see below) */<br>
<span style=" text-indent: 0.1800in;"></span>int am_error; /* [out arg] result of this sub-op (an errno) */<br>
<span style=" text-indent: 0.1800in;"></span>char *am_attrname; /* attribute name to work with */<br>
<span style=" text-indent: 0.1800in;"></span>char *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */<br>
<span style=" text-indent: 0.1800in;"></span>int am_length; /* [in/out arg] length of value */<br>
<span style=" text-indent: 0.1800in;"></span>int am_flags; /* flags (bit-wise OR of #defines below) */</p>
</EM><p><font size=3>The <font size=3><I>am_opcode</I> <font size=3>field defines how the remaining fields are to be interpreted and can take on one of the following values:</p>
<p><span style=" text-indent: 0.1800in;"></span><font size=3><EM>ATTR_OP_GET /* return the indicated attr's value */<br>
<span style=" text-indent: 0.1800in;"></span>ATTR_OP_SET /* set/create the indicated attr/value pair */<br>
<span style=" text-indent: 0.1800in;"></span>ATTR_OP_REMOVE /* remove the indicated attr */</p>
</EM><p><font size=3>The <font size=3><I>am_error</I> <font size=3>field will contain the appropriate error result code if that sub-operation fails. The result codes for a given sub-operation are a subset of the result codes that are possible from the corresponding single-attribute func- tion call. For example, the result code possible from an <font size=3><EM>ATTR_OP_GET</EM> <font size=3>sub-operation are a subset of those that can be returned from an <font size=3><I>attr_get</I> <font size=3>function call.</p>
<p><font size=3>The <font size=3><I>am_attrname</I> <font size=3>field is a pointer to a NULL terminated string giving the attribute name that the sub-operation should operate on.</p>
<p><font size=3>The <font size=3><I>am_attrvalue, am_length</I> <font size=3>and <font size=3><I>am_flags</I> <font size=3>fields are used to store the value of the named attribute, and some control flags for that sub-operation, respectively. Their use varies depending on the value of the <font size=3><I>am_opcode</I> <font size=3>field.</p>
<a name="ATTR_OP_GET"></a><h2>ATTR_OP_GET</h2>
<table width="100%"  rules="none"  frame="none"  cols="2">
<tr valign="top" align="left">
<td valign="top" align="left"  width="20.0000%">
</td>
<td valign="top" align="left"  width="80.0000%">
<p><font size=3>The <font size=3><I>am_attrvalue</I> <font size=3>field is a pointer to a empty buffer that will be overwritten with the value of the named attribute. The <font size=3><I>am_length</I> <font size=3>field is initially the total size of the memory buffer that the <font size=3><I>am_attrvalue</I> <font size=3>field points to. After the operation, the <font size=3><I>am_length</I> <font size=3>field contains the</p>
</td>
</tr>
</table>

<!-- Page: 2  -->
<!-- left  margin: 100 -->
<!-- right margin: 750 -->
<p><span style=" text-indent: 1.3000in;"></span><font size=3>actual size of the attribute´s value. The <font size=3><I>am_flags</I> <font size=3>field may be set to the <font size=3><EM>ATTR_ROOT<br>
<span style=" text-indent: 1.3000in;"></span></EM>flag. If the process has appropriate priviledges, the ROOT namespace will be searched for<br>
<span style=" text-indent: 1.3000in;"></span>the named attribute, otherwise the USER namespace will be searched.</p>

<table width="100%"  rules="none"  frame="none"  cols="3">
<tr valign="top" align="left">
<td valign="top" align="left"  width="16.4615%">
<p><font size=2><B>ATTR_OP_SET</p>
</B><p><font size=2><B>ATTR_OP_REMOVE</p>
</B></td>
<td valign="top" align="left"  width="3.5385%">
</td>
<td valign="top" align="left"  width="80.0000%">
<p><font size=3>The <font size=3><I>am_attrvalue</I> <font size=3>and <font size=3><I>am_length</I> <font size=3>fields contain the new value for the given attribute name and its length. The <font size=3><EM>ATTR_ROOT</EM> <font size=3>flag may be set in the <font size=3><I>am_flags</I> <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 size=3><EM>ATTR_CREATE</EM> <font size=3>and the <font size=3><EM>ATTR_REPLACE</EM> <font size=3>flags may also be set in the <font size=3><I>am_flags</I> <font size=3>field (but not simultaneously). If the <font size=3><EM>ATTR_CREATE</EM> <font size=3>flag is set, the sub-operation will set the <font size=3><I>am_error</I> <font size=3>field to EEXIST if the named attribute already exists. If the <font size=3><EM>ATTR_REPLACE</EM> <font size=3>flag is set, the sub-operation will set the <font size=3><I>am_error</I> <font size=3>field to ENOATTR if the named attribute does not already 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.</p>
<p><font size=3>The <font size=3><I>am_attrvalue</I> <font size=3>and <font size=3><I>am_length</I> <font size=3>fields are not used and are ignored. The <font size=3><I>am_flags</I> <font size=3>field may be set to the <font size=3><EM>ATTR_ROOT</EM> <font size=3>flag. If the process has appropriate priviledges, the ROOT namespace will be searched for the named attribute, otherwise the USER names- pace will be searched.</p>
</td>
</tr>
</table>
<p><font size=3>The <font size=3><I>flags</I> <font size=3>argument to the <font size=3><I>attr_multi</I> <font size=3>call is used to control following of symbolic links in the <font size=3><I>path</I> <font size=3>argument. The default is to follow symbolic links, <font size=3><I>flags</I> <font size=3>should be set to ATTR_DONTFOLLOW to not follow symbolic links.</p>
<p><font size=3><I>attr_multi</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-<br>
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 other than ATTR_DONTFOLLOW was set in the <font size=3><I>flag</I> <font size=3>argument.</p>
<p><font size=3><I>Path,</I> <font size=3>or <font size=3><I>oplist</I> <font size=3>points outside the allocated address space of the process.</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.5900in;"></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>

<table width="100%"  rules="none"  frame="none"  cols="2">
<tr valign="top" align="left">
<td valign="top" align="left"  width="73.5385%">
<p><font size=3><I>attr_multif</I> <font size=3>will fail if:</p>
<p><font size=2>[EINVAL] <font size=3>A bit was set in the <font size=3><I>flag</I> <font size=3>argument, or <font size=3><I>fd</I> <font size=3>refers to a socket, not a file.</p>
</td>
<td valign="top" align="left"  width="26.4615%">
</td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="73.5385%">
<p><font size=2>[EFAULT] <font size=3><I>Oplist</I> <font size=3>points outside the allocated address space of the process.</p>
</td>
<td valign="top" align="left"  width="26.4615%">
</td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="73.5385%">
<p><font size=2>[EBADF] <font size=3><I>Fd</I> <font size=3>does not refer to a valid descriptor.</p>
</td>
<td valign="top" align="left"  width="26.4615%">
</td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="73.5385%">
</td>
<td valign="top" align="left"  width="26.4615%">
</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_list(2), attr_list(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 of the <font size=3><I>attr_multi</I> <font size=3>call, 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 indicate the error. Note that the individual operations listed in the <font size=3><I>oplist</I> <font size=3>array each have their own error return fields. The <font size=3><I>errno</I> <font size=3>variable only records the result of the <font size=3><I>attr_multi</I> <font size=3>call itself, not the result of any of the sub-operations.<br>
</p>
</body>
</html>