Linux  »  Man Pages
find in page | jump to first hit | clear highlight

       fssetdm_by_handle, 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 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 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 filesys-
       tem.  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 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_fshan-
       dle(), and handle_to_fshandle().

SEE ALSO

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

DIAGNOSTICS

       The function free_handle() has no failure indication.  The other  func-
       tions return the value 0 to the calling process if they succeed; other-
       wise, they return the value -1 and set errno to indicate the error:

       [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.

                                                                     HANDLE(3)