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.

SEE ALSO

       open(2), readlink(2), attr_multi(3), attr_list(3), xfsctl(3), xfs(5).

                                                                                        HANDLE(3)