path_to_handle, path_to_fshandle, fd_to_handle, han
dle_to_fshandle, open_by_handle, readlink_by_handle,
attr_multi_by_handle, attr_list_by_handle, fssetdm_by_han
dle, free_handle - file handle operations
C SYNOPSIS
#include <sys/types.h>
#include <xfs/handle.h>
int path_to_handle (char *path, void **hanp,
size_t *hlen);
int path_to_fshandle (char *path, void **hanp,
size_t *hlen);
int fd_to_handle (int fd, void **hanp, size_t *hlen);
int handle_to_fshandle (void *hanp, size_t hlen,
void **fshanp, size_t *fshlen);
int open_by_handle (void *hanp, size_t hlen,
int oflag);
int readlink_by_handle (void *hanp, size_t hlen,
void *buf, size_t bs);
int attr_multi_by_handle (void *hanp, size_t hlen,
void *buf, int rtrvcnt,
int flags);
int attr_list_by_handle (void *hanp, size_t hlen,
char *buf, size_t bufsiz,
int flags,
struct attrlist_cursor *cursor);
int fssetdm_by_handle (void *hanp, size_t hlen,
struct fsdmidata *fssetdm);
void free_handle (void *hanp, size_t hlen);
DESCRIPTION
These functions provide a way to perform certain filesys
tem operations without using a file descriptor to access
filesystem objects. They are intended for use by a lim
ited set of system utilities such as backup programs.
They are supported only by the XFS filesystem. Link with
the libhandle library to access these functions.
A 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
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 indi
cates the number of bytes in the handle which are pointed
to by the pointer.
The path_to_handle() function returns the handle for the
object given by the path argument. If the final component
of the path name is a symbolic link, the handle returned
is that of the link itself.
The path_to_fshandle() function returns the handle for the
filesystem in which the object given by the path argument
resides.
The fd_to_handle() function returns the handle for the
object referenced by the fd argument, which must be a
valid file descriptor.
The handle_to_fshandle() function returns the handle for
the filesystem in which the object referenced by the han
dle given by the hanp and hlen arguments resides.
The open_by_handle() function opens a file descriptor for
the object referenced by a handle. It is analogous and
identical to open(2) with the exception of accepting han
dles instead of path names.
The readlink_by_handle() function returns the contents of
a symbolic link referenced by a handle.
The attr_multi_by_handle() function manipulates multiple
user attributes on a filesystem object. It is analogous
and identical to attr_multif(3) except that a handle is
specified instead of a file descriptor.
The attr_list_by_handle() function returns the names of
the user attributes of a filesystem object. It is analo
gous and identical to attr_listf(3) except that a handle
is specified instead of a file descriptor.
The fssetdm_by_handle() function sets the di_dmevmask and
di_dmstate fields in an XFS on-disk inode. It is analo
gous to the XFS_IOC_FSSETDM ioctl(2) command (see also
xfs(5)), except that a handle is specified instead of a
file descriptor.
The free_handle() function frees the storage allocated for
handles returned by the following functions: path_to_han
dle(), path_to_fshandle(), fd_to_handle(), and han
dle_to_fshandle().
open(2), ioctl(2), readlink(2), attr_multi(3),
attr_list(3), xfs(5).
DIAGNOSTICS
The function free_handle() 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 errno to indicate the error:
[EACCES] Search permission was denied for a compo
nent of path.
[EBADF] fd is not a valid and open file descriptor.
[EFAULT] An argument pointed to an invalid address.
[EINVAL] path is in a filesystem that does not sup
port these functions.
[ELOOP] Too many symbolic links were encountered in
translating the path name.
[ENAMETOOLONG] A component of path or the entire length of
path exceeds filesystem limits.
[ENOENT] A component of path does not exist.
[EPERM] The caller does not have sufficient privi
leges.
Man(1) output converted with
man2html