Man Linux: Main Page and Category List

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.

       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)