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, getparents_by_handle, getparentpaths_by_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);

int getparents_by_handle(void *hanp, size_t hlen, parent_t *buf, size_t bufsiz, parent_cursor_t *cursor, unsigned int *count, unsigned int *more);

int getparentpaths_by_handle(void *hanp, size_t hlen, parent_t *buf, size_t bufsiz, parent_cursor_t *cursor, unsigned int *count, unsigned int *more);

DESCRIPTION

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 libhandle library to access these functions.

A handle, hanp, 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 (hanp) and a size (hlen). The size, hlen, 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 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 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(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 analogous 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 analogous to the XFS_IOC_FSSETDM xfsctl(3) command, except that a handle is specified instead of a file.