path_to_handle,   path_to_fshandle,   fd_to_handle,   han­
       dle_to_fshandle,    open_by_handle,    readlink_by_handle,
       attr_multi_by_handle, attr_list_by_handle, fssetdm_by_han­
       dle, free_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);


DESCRIPTION

       These functions provide a way to perform certain  filesys­
       tem  operations  without using a file descriptor to access
       filesystem objects.  They are intended for use by  a  lim­
       ited  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

       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 indi­
       cates 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 han­
       dle 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  han­
       dles 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  analo­
       gous  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 analo­
       gous to the XFS_IOC_FSSETDM  ioctl(2)  command  (see  also
       xfs(5)),  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_han­
       dle(),  path_to_fshandle(),   fd_to_handle(),   and   han­
       dle_to_fshandle().

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


DIAGNOSTICS

       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]       Search  permission  was denied for a compo­
                      nent 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  sup­
                      port 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 privi­
                      leges.


Man(1) output converted with man2html