.TH HANDLE 3 
.SH NAME
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
.SH C SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <xfs/handle.h>
.PP
.B "int path_to_handle (char *path, void **hanp,"
.B "                    size_t *hlen);"
.PP
.B "int path_to_fshandle (char *path, void **hanp,"
.B "                      size_t *hlen);"
.PP
.B "int fd_to_handle (int fd, void **hanp, size_t *hlen);
.PP
.B "int handle_to_fshandle (void *hanp, size_t hlen,"
.B "                        void **fshanp, size_t *fshlen);
.PP
.B "int open_by_handle (void *hanp, size_t hlen,"
.B "                    int oflag);"
.PP
.B "int readlink_by_handle (void *hanp, size_t hlen,"
.B "                        void *buf, size_t bs);
.PP
.B "int attr_multi_by_handle (void *hanp, size_t hlen,"
.B "                          void *buf, int rtrvcnt,"
.B "                          int flags);"
.PP
.B "int attr_list_by_handle (void *hanp, size_t hlen,"
.B "                         char *buf, size_t bufsiz,"
.B "                         int flags,"
.B "                         struct attrlist_cursor *cursor);"
.PP
.B "int fssetdm_by_handle (void *hanp, size_t hlen,"
.B "                       struct fsdmidata *fssetdm);"
.PP
.B "void free_handle (void *hanp, size_t hlen);
.Op
.SH DESCRIPTION
.PP
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
.I libhandle
library to access these functions.
.sp
A
.I handle
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.
.P
The \f2path_to_handle\f1() function
returns the handle for the object given by the
.I path
argument.
If the final component of the path name is a symbolic link,
the handle returned is that of the link itself.
.P
The \f2path_to_fshandle\f1() function
returns the handle for the filesystem
in which the object given by the
.I path
argument resides.
.P
The \f2fd_to_handle\f1() function
returns the handle for the object referenced by the
.I fd
argument,
which must be a valid file descriptor.
.P
The \f2handle_to_fshandle\f1() function
returns the handle for the filesystem
in which the object referenced by the
handle given by the
.I hanp
and
.I hlen
arguments resides.
.P
The \f2open_by_handle\f1() function
opens a file descriptor for the object referenced
by a handle.
It is analogous and identical to
.I open(2)
with the exception of accepting handles instead of path names.
.P
The \f2readlink_by_handle\f1() function
returns the contents of a symbolic link
referenced by a handle.
.P
The \f2attr_multi_by_handle\f1() function
manipulates multiple user attributes on a 
filesystem object.
It is analogous and identical to
.I attr_multif(3)
except that a handle is specified instead of a file descriptor.
.P
The \f2attr_list_by_handle\f1() function returns 
the names of the user attributes of a filesystem object.
It is analogous and identical to
.I attr_listf(3)
except that a handle is specified instead of a file descriptor.
.P
The \f2fssetdm_by_handle\f1() function sets the
di_dmevmask and di_dmstate fields in an XFS on-disk inode.
It is analogous to the \f2XFS_IOC_FSSETDM\f1
.I ioctl(2)
command (see also
.I xfs(5)), except that a handle is specified instead of a file descriptor.
.P
The \f2free_handle\f1() function
frees the storage allocated for handles
returned by the following functions:
\f2path_to_handle\f1(),
\f2path_to_fshandle\f1(),
\f2fd_to_handle\f1(),
and
\f2handle_to_fshandle\f1().
.SH "SEE ALSO"
open(2),
ioctl(2),
readlink(2),
attr_multi(3),
attr_list(3),
xfs(5).
.SH "DIAGNOSTICS"
.PP
The function
\f2free_handle\f1()
has no failure indication.
The other functions
return the value 0 to the calling process
if they succeed;
otherwise, they return the value -1 and set 
.I errno
to indicate the error:
.sp
.TP 15
.SM
\%[EACCES]
Search permission was denied for a component of
.IR path .
.TP 15
.SM
\%[EBADF]
.I fd
is not a valid and open file descriptor.
.TP 15
.SM
\%[EFAULT]
An argument pointed to an invalid address.
.TP 15
.SM
\%[EINVAL]
.I path
is in a filesystem that does not support these functions.
.TP 15
.SM
\%[ELOOP]
Too many symbolic links were encountered in translating the path name.
.TP 15
.SM
\%[ENAMETOOLONG]
A component of
.I path
or the entire length of
.I path
exceeds filesystem limits.
.TP 15
.SM
\%[ENOENT]
A component of
.I path
does not exist.
.TP 15
.SM
\%[EPERM]
The caller does not have sufficient privileges.