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

Revision 1.1, Thu Jan 25 19:55:30 2001 UTC (16 years, 8 months ago) by xfs
Branch: MAIN
CVS Tags: HEAD 

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/types.h&gt;">#include &lt;sys/types.h&gt;</a><br>
<a href="##include &lt;xfs/handle.h&gt;">#include &lt;xfs/handle.h&gt;</a><br>
<a href="#int path_to_handle (char *path, void **hanp,">int path_to_handle (char *path, void **hanp,</a><br>
<a href="#int path_to_fshandle (char *path, void **hanp,">int path_to_fshandle (char *path, void **hanp,</a><br>
<a href="#int fd_to_handle (int fd, void **hanp, size_t *hlen);">int fd_to_handle (int fd, void **hanp, size_t *hlen);</a><br>
<a href="#int handle_to_fshandle (void *hanp, size_t hlen,">int handle_to_fshandle (void *hanp, size_t hlen,</a><br>
<a href="#int open_by_handle (void *hanp, size_t hlen,">int open_by_handle (void *hanp, size_t hlen,</a><br>
<a href="#int readlink_by_handle (void *hanp, size_t hlen,">int readlink_by_handle (void *hanp, size_t hlen,</a><br>
<a href="#int attr_multi_by_handle (void *hanp, size_t hlen,">int attr_multi_by_handle (void *hanp, size_t hlen,</a><br>
<a href="#int attr_list_by_handle (void *hanp, size_t hlen,">int attr_list_by_handle (void *hanp, size_t hlen,</a><br>
<a href="#int fssetdm_by_handle (void *hanp, size_t hlen,">int fssetdm_by_handle (void *hanp, size_t hlen,</a><br>
<a href="#void free_handle (void *hanp, size_t hlen);">void free_handle (void *hanp, size_t hlen);</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:52 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>path_to_handle, path_to_fshandle, fd_to_handle, handle_to_fshandle, open_by_handle, readlink_by_handle, attr_multi_by_handle, attr_list_by_handle, fssetdm_by_handle, free_handle - file handle operations</font></p>
<a name="C SYNOPSIS"></a><h2>C SYNOPSIS</h2><a name="#include &lt;sys/types.h&gt;"></a><h2>#include &lt;sys/types.h&gt;</h2><a name="#include &lt;xfs/handle.h&gt;"></a><h2>#include &lt;xfs/handle.h&gt;</h2><a name="int path_to_handle (char *path, void **hanp,"></a><h2>int path_to_handle (char *path, void **hanp,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="27%">
</td>
<td valign="top" align="left" width="72%">
<p><font size=3><B>size_t *hlen);</B></font></p>
</td>
</tr>
</table>
<a name="int path_to_fshandle (char *path, void **hanp,"></a><h2>int path_to_fshandle (char *path, void **hanp,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="28%">
</td>
<td valign="top" align="left" width="71%">
<p><font size=3><B>size_t *hlen);</B></font></p>
</td>
</tr>
</table>
<a name="int fd_to_handle (int fd, void **hanp, size_t *hlen);"></a><h2>int fd_to_handle (int fd, void **hanp, size_t *hlen);</h2><a name="int handle_to_fshandle (void *hanp, size_t hlen,"></a><h2>int handle_to_fshandle (void *hanp, size_t hlen,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="29%">
</td>
<td valign="top" align="left" width="70%">
<p><font size=3><B>void **fshanp, size_t *fshlen);</B></font></p>
</td>
</tr>
</table>
<a name="int open_by_handle (void *hanp, size_t hlen,"></a><h2>int open_by_handle (void *hanp, size_t hlen,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="27%">
</td>
<td valign="top" align="left" width="72%">
<p><font size=3><B>int oflag);</B></font></p>
</td>
</tr>
</table>
<a name="int readlink_by_handle (void *hanp, size_t hlen,"></a><h2>int readlink_by_handle (void *hanp, size_t hlen,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="29%">
</td>
<td valign="top" align="left" width="70%">
<p><font size=3><B>void *buf, size_t bs);</B></font></p>
</td>
</tr>
</table>
<a name="int attr_multi_by_handle (void *hanp, size_t hlen,"></a><h2>int attr_multi_by_handle (void *hanp, size_t hlen,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="30%">
</td>
<td valign="top" align="left" width="69%">
<p><font size=3><B>void *buf, int rtrvcnt,</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="30%">
</td>
<td valign="top" align="left" width="69%">
<p><font size=3><B>int flags);</B></font></p>
</td>
</tr>
</table>
<a name="int attr_list_by_handle (void *hanp, size_t hlen,"></a><h2>int attr_list_by_handle (void *hanp, size_t hlen,</h2>
<table width="100%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="30%">
</td>
<td valign="top" align="left" width="70%">
<p><font size=3><B>char *buf, size_t bufsiz,</B></font></p>
</td>
</tr>
</table>

<table width="100%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="30%">
</td>
<td valign="top" align="left" width="70%">
<p><font size=3><B>int flags,</B></font></p>
</td>
</tr>
</table>

<table width="100%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="30%">
</td>
<td valign="top" align="left" width="70%">
<p><font size=3><B>struct attrlist_cursor *cursor);</B></font></p>
</td>
</tr>
</table>
<a name="int fssetdm_by_handle (void *hanp, size_t hlen,"></a><h2>int fssetdm_by_handle (void *hanp, size_t hlen,</h2>
<table width="99%" rules="none" frame="none" cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td valign="top" align="left" width="29%">
</td>
<td valign="top" align="left" width="70%">
<p><font size=3><B>struct fsdmidata *fssetdm);</B></font></p>
</td>
</tr>
</table>
<a name="void free_handle (void *hanp, size_t hlen);"></a><h2>void free_handle (void *hanp, size_t hlen);</h2><a name="DESCRIPTION"></a><h2>DESCRIPTION</h2><p style="margin-left: 18%"><font size=3>These functions provide a way to perform certain filesystem operations without using a file descriptor to access filesystem objects. They are intended for use by a limited set of system utilities such as backup programs. They are supported only by the XFS filesystem. Link with the</font> <font size=3><I>libhandle</I></font> <font size=3>library to access these functions.</font></p>
<p style="margin-left: 18%"><font size=3>A</font> <font size=3><I>handle</I></font> <font size=3>uniquely identifies a filesystem object or an entire filesystem. There is one and only one handle per filesystem or filesystem object. Handles consist of some number of bytes. The size of a handle (i.e. the number of bytes comprising it) varies by the type of handle and may vary for different objects of the same type. The content of a handle is opaque to applications. Since handle sizes vary and their contents are opaque, handles are described by two quantities, a pointer and a size. The size indicates the number of bytes in the handle which are pointed to by the pointer.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>path_to_handle</I></font><font size=3>() function returns the handle for the object given by the</font> <font size=3><I>path</I></font> <font size=3>argument. If the final component of the path name is a symbolic link, the handle returned is that of the link itself.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>path_to_fshandle</I></font><font size=3>() function returns the handle for the filesystem in which the object given by the</font> <font size=3><I>path</I></font> <font size=3>argument resides.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>fd_to_handle</I></font><font size=3>() function returns the handle for the object referenced by the</font> <font size=3><I>fd</I></font> <font size=3>argument, which must be a valid file descriptor.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>handle_to_fshandle</I></font><font size=3>() function returns the handle for the filesystem in which the object referenced by the handle given by the</font> <font size=3><I>hanp</I></font> <font size=3>and</font> <font size=3><I>hlen</I></font> <font size=3>arguments resides.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>open_by_handle</I></font><font size=3>() function opens a file descriptor for the object referenced by a handle. It is analogous and identical to</font> <font size=3><I>open(2)</I></font> <font size=3>with the exception of accepting handles instead of path names.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>readlink_by_handle</I></font><font size=3>() function returns the contents of a symbolic link referenced by a handle.</font><br>
</p>

<!-- Page: 2  -->
<!-- left  margin: 220 -->
<!-- right margin: 750 -->
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>attr_multi_by_handle</I></font><font size=3>() function manipulates multiple user attributes on a filesystem object. It is analogous and identical to</font> <font size=3><I>attr_multif(2)</I></font> <font size=3>except that a handle is specified instead of a file descriptor.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>attr_list_by_handle</I></font><font size=3>() function returns the names of the user attributes of a filesystem object. It is analogous and identical to</font> <font size=3><I>attr_listf(2)</I></font> <font size=3>except that a handle is specified instead of a file descriptor.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>fssetdm_by_handle</I></font><font size=3>() function sets the di_dmevmask and di_dmstate fields in an XFS on&shy;disk inode. It is analogous to the</font> <font size=3><I>F_FSSETDM</I></font> <font size=3>subfunction of</font> <font size=3><I>fcntl(2)</I></font> <font size=3>except that a handle is specified instead of a file descriptor.</font></p>
<p style="margin-left: 18%"><font size=3>The</font> <font size=3><I>free_handle</I></font><font size=3>() function frees the storage allocated for handles returned by the following functions:</font> <font size=3><I>path_to_handle</I></font><font size=3>(),</font> <font size=3><I>path_to_fshandle</I></font><font size=3>(),</font> <font size=3><I>fd_to_handle</I></font><font size=3>(), and</font> <font size=3><I>handle_to_fshandle</I></font><font size=3>().</font></p>
<a name="SEE ALSO"></a><h2>SEE ALSO</h2><p style="margin-left: 18%"><font size=3>open(2), readlink(2), attr_multi(2), attr_list(2), fcntl(2).</font></p>
<a name="DIAGNOSTICS"></a><h2>DIAGNOSTICS</h2><p style="margin-left: 18%"><font size=3>The function</font> <font size=3><I>free_handle</I></font><font size=3>() has no failure indication. The other functions return the value 0 to the calling process if they succeed; otherwise, they return the value &shy;1 and set</font> <font size=3><I>errno</I></font> <font size=3>to indicate the error:</font>
<table width="98%" 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>[EACCES] [EBADF]</font></p>
<p><font size=2>[EFAULT]</font></p>
<p><font size=2>[EINVAL]</font></p>
<p><font size=2>[ELOOP]</font></p>
</td>
<td valign="top" align="left" width="5%">
</td>
<td valign="top" align="left" width="67%">
<p><font size=3>Search permission was denied for a component of</font> <font size=3><I>path</I></font><font size=3>.</font></p>
<p><font size=3><I>fd</I></font> <font size=3>is not a valid and open file descriptor.</font></p>
<p><font size=3>An argument pointed to an invalid address.</font></p>
<p><font size=3><I>path</I></font> <font size=3>is in a filesystem that does not support these functions.</font></p>
<p><font size=3>Too many symbolic links were encountered in translating the path name.</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="32%">
</p>
</td>
<td valign="top" align="left" width="67%">
<p><font size=3>A component of</font> <font size=3><I>path</I></font> <font size=3>or the entire length of</font> <font size=3><I>path</I></font> <font size=3>exceeds filesystem limits.</font></p>
</td>
</tr>
</table>
</p>
<p style="margin-left: 18%"><font size=2>[ENOENT]</font> <font size=3>A component of</font> <font size=3><I>path</I></font> <font size=3>does not exist.</font></p>
<p style="margin-left: 18%"><font size=2>[EPERM]</font> <font size=3>The caller does not have sufficient privileges.</font><br>
</p>
</body>
</html>