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
|
size_t *hlen); |
|
size_t *hlen); |
|
void **fshanp, size_t *fshlen); |
|
int oflag); |
|
void *buf, size_t bs); |
|
void *buf, int rtrvcnt, |
|
int flags); |
|
char *buf, size_t bufsiz, |
|
int flags, |
|
struct attrlist_cursor *cursor); |
|
struct fsdmidata *fssetdm); |
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 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 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(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 descriptor.
The fssetdm_by_handle() function sets the di_dmevmask and di_dmstate fields in an XFS ondisk inode. It is analogous to the F_FSSETDM subfunction of fcntl(2) 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_handle(), path_to_fshandle(), fd_to_handle(), and handle_to_fshandle().
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] [EBADF] [EFAULT] [EINVAL] [ELOOP] |
Search permission was denied for a component of path. fd is not a valid and open file descriptor. An argument pointed to an invalid address. path is in a filesystem that does not support these functions. 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 privileges.