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
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);
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. Device
management capabilities or root privileges are required to use
open_by_handle() readlink_by_handle(), attr_multi_by_handle(),
attr_list_by_handle(), and fssetdm_by_handle(). Link with the -ldm
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 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.
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 handle given by the hanp and hlen
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 handles 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(2)
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 analogous and identical to
attr_listf(2) except that a handle is specified instead of a file
The fssetdm_by_handle() function sets the di_dmevmask and di_dmstate
fields in an XFS on-disk inode. It is analogous to the F_FSSETDM
subfunction of fcntl(2) except that a handle is specified instead of a
The free_handle() function frees the storage allocated for handles
returned by the following functions: path_to_handle(),
path_to_fshandle(), fd_to_handle(), and handle_to_fshandle().
In IRIX releases prior to 6.5 the declarations for these functions were
obtained by including <sys/fs/xfs_handle.h> instead of <sys/handle.h>.
open(2), readlink(2), attr_multi(2), attr_list(2), fcntl(2).
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 component 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 support these
[ELOOP] Too many symbolic links were encountered in translating
the path name.
[ENAMETOOLONG] A component of path or the entire length of path exceeds
[ENOENT] A component of path does not exist.
[EPERM] The caller does not have sufficient privileges.
PPPPaaaaggggeeee 3333 [ Back ]