# handle

## 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.  This function is not supported on
           Linux.
    
           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**().
    
           The **getparents_by_handle**() function returns an array of **parent_t**
           structures for each hardlink to the inode represented by the given
           handle.  The parent structure encodes the parent inode number,
           generation number and the basename of the link.  **This function is**
           **not operational on Linux.**
    
           The **getparentpaths_by_handle**() function is identical to the
           **getparents_by_handle**() function except that instead of returning
           the basename it returns the path of the link up to the mount
           point.  **This function is also not operational on Linux.**
    


## RETURN VALUE



           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.
    


## ERRORS



           **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
                  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 privileges.
    


* * *