HANDLE(3) HANDLE(3)
NAME
path_to_handle, path_to_fshandle, handle_to_fshandle, open_by_handle,
readlink_by_handle, attr_multi_by_handle, attr_list_by_handle,
fssetdm_by_handle, free_handle - file(1,n) 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 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 filesystem operations
without using a file(1,n) descriptor to access(2,5) filesystem objects. They are
intended for use by a limited set(7,n,1 builtins) of system utilities such as backup
programs. They are supported only by the XFS filesystem. Link with
the libhandle library to access(2,5) these functions.
A handle uniquely identifies a filesystem object or an entire filesys-
tem. 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(1,8) 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(1,2), the handle returned is that of the link(1,2) itself.
The path_to_fshandle() function returns the handle for the filesystem
in(1,8) which the object given by the path argument resides.
The handle_to_fshandle() function returns the handle for the filesystem
in(1,8) which the object referenced by the handle given by the hanp and hlen
arguments resides.
The open_by_handle() function opens a file(1,n) descriptor for the object
referenced by a handle. It is analogous and identical to open(2,3,n)(2) with
the exception of accepting handles instead of path names.
The readlink_by_handle() function returns the contents of a symbolic
link(1,2) 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(1,n)
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(3) except that a handle is specified instead of a file(1,n)
descriptor.
The fssetdm_by_handle() function sets the di_dmevmask and di_dmstate
fields in(1,8) an XFS on-disk inode. It is analogous to the XFS_IOC_FSSETDM
xfsctl(3) command, except that a handle is specified instead of a file.
The free_handle() function frees the storage allocated for handles
returned by the following functions: path_to_handle(), path_to_fshan-
dle(), and handle_to_fshandle().
SEE ALSO
open(2,3,n)(2), readlink(1,2)(2), attr_multi(3), attr_list(3), xfsctl(3), xfs(5).
DIAGNOSTICS
The function free_handle() has no failure indication. The other func-
tions return the value 0 to the calling process if(3,n) they succeed; other-
wise, they return the value -1 and set(7,n,1 builtins) errno to indicate the error:
[EACCES] Search permission was denied for a component of path.
[EBADF] fd is not a valid and open(2,3,n) file(1,n) descriptor.
[EFAULT] An argument pointed to an invalid address.
[EINVAL] path is in(1,8) a filesystem that does not support these
functions.
[ELOOP] Too many symbolic links were encountered in(1,8) 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 privileges.
HANDLE(3)