[BACK]Return to attr_get.html CVS log [TXT][DIR] Up to [Development] / xfs-website.orig / manpages
File: [Development] / xfs-website.orig / manpages / attr_get.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_get, attr_getf - get the value of a user attribute 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_get (const char</B> <font size=3>*<font size=3><B>path, const char</B> <font size=3>*<font size=3><B>attrname,<br>
<span style=" text-indent: 0.4200in;"></span>char</B> <font size=3>*<font size=3><B>attrvalue, int</B> <font size=3>*<font size=3><B>valuelength, int flags);</p>
</B><p><font size=3><B>int attr_getf (int fd, const char</B> <font size=3>*<font size=3><B>attrname,<br>
<span style=" text-indent: 0.4500in;"></span>char</B> <font size=3>*<font size=3><B>attrvalue, int</B> <font size=3>*<font size=3><B>valuelength, 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_get</I> <font size=3>and <font size=3><I>attr_getf</I> <font size=3>functions provide a way to retrieve the value of an attribute.</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. If the attribute <font size=3><I>attrname</I> <font size=3>exists, the value associated with it will be copied into the <font size=3><I>attrvalue</I> <font size=3>buffer. The <font size=3><I>valuelength</I> <font size=3>argument is an input/output argument that on the call to <font size=3><I>attr_get</I> <font size=3>should contain the maximum size of attribute value the process is willing to accept. On return, the <font size=3><I>valuelength</I> <font size=3>will have been modified to show the actual size of the attribute value returned. The <font size=3><I>flags</I> <font size=3>argument can contain the following symbols bitwise ORŽed together:</p>

<table width="100%"  rules="none"  frame="none"  cols="3">
<tr valign="top" align="left">
<td valign="top" align="left"  width="86.7692%">
<p><font size=2>ATTR_ROOT <font size=3>Look for <font size=3><I>attrname</I> <font size=3>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.</p>
</td>
<td valign="top" align="left"  width="1.0000%">
</td>
<td valign="top" align="left"  width="12.3077%">
<p><font size=3>(limited to use</p>
</td>
</tr>
<tr valign="top" align="left">
<td valign="top" align="left"  width="66.7692%">
<p><font size=3> by super-user only)</p>
</td>
<td valign="top" align="left"  width="1.0000%">
</td>
<td valign="top" align="left"  width="12.3077%">
</td>
</tr>
</table>
<br>
<p><font size=2>ATTR_DONTFOLLOW <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_get</I> <font size=3>function call. The default<br>
<span style=" text-indent: 1.3000in;"></span>is to follow symbolic links.</p>
<p><font size=3><I>attr_get</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="9.5385%">
<p><font size=2>[ENOATTR]</p>
<p><font size=2>[E2BIG]</p>
<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.1538%">
</td>
<td valign="top" align="left"  width="84.3077%">
<p><font size=3>The attribute name given is not associated with the indicated filesystem object.</p>
<p><font size=3>The value of the given attribute is too large to fit into the buffer. The integer that the <font size=3><I>valuelength</I> <font size=3>argument points to has been modified to show the actual number of bytes that would be required to store the value of that attribute.</p>
<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.</p>
<p><font size=3><I>Path, attrname, attrvalue,</I> <font size=3>or <font size=3><I>valuelength</I> <font size=3>points outside the allocated address space of the pro- cess.</p>
<p><font size=3>A path name lookup involved too many symbolic links.</p>
</td>
</tr>
</table>
<br>
<p><font size=2>[ENAMETOOLONG]<br>
<span style=" text-indent: 1.0200in;"></span><font size=3>The length of <font size=3><I>path</I> <font size=3>exceeds <sub>{</sub><font size=3><I><sub>MAXPATHLEN</sub></I><font size=3><sub>},</sub> or a pathname component is longer than <sub>{</sub><font size=3><I><sub>MAXNAME-</sub></p>
</I><p><span style=" text-indent: 1.0200in;"></span><font size=2><I>LEN</I><font size=2>}.<br>
</p>

<!-- Page: 2  -->
<!-- left  margin: 100 -->
<!-- right margin: 750 -->
<p><font size=3><I>attr_getf</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="9.5385%">
<p><font size=2>[ENOATTR]</p>
<p><font size=2>[E2BIG]</p>
<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="4.3077%">
</td>
<td valign="top" align="left"  width="86.1538%">
<p><font size=3>The attribute name given is not associated with the indicated filesystem object.</p>
<p><font size=3>The value of the given attribute is too large to fit into the buffer. The integer that the <font size=3><I>valuelength</I> <font size=3>argument points to has been modified to show the actual numnber of bytes that would be required to store the value of that attribute.</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 <font size=3><I>fd</I> <font size=3>refers to a socket, not a file.</p>
<p><font size=3><I>Attrname, attrvalue,</I> <font size=3>or <font size=3><I>valuelength</I> <font size=3>points outside the allocated address space of the process.</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_list(2), attr_listf(2)<br>
attr_multi(2), attr_multif(2)<br>
attr_remove(2), attr_removef(2),<br>
attr_set(2), attr_setf(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>