Seth Woolley's Man Viewer

handle(3) - attr_list_by_handle, attr_multi_by_handle, free_handle, fssetdm_by_handle, handle_to_fshandle, open_by_handle, path_to_fshandle, path_to_handle, readlink_by_handle - file handle operations - man 3 handle

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

HANDLE(3)                                                            HANDLE(3)



NAME
       path_to_handle,  path_to_fshandle,  handle_to_fshandle, open_by_handle,
       readlink_by_handle,     attr_multi_by_handle,      attr_list_by_handle,
       fssetdm_by_handle, free_handle - file(1,n) 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(1,n) descriptor to access(2,5) filesystem objects.  They are
       intended  for  use  by a limited set(7,n,1 builtins) of system utilities such as backup
       programs.  They are supported only by the XFS  filesystem.   Link  with
       the libhandle library to access(2,5) 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(1,8) 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(1,2), the handle returned is that of the link(1,2) itself.

       The  path_to_fshandle()  function returns the handle for the filesystem
       in(1,8) which the object given by the path argument resides.

       The handle_to_fshandle() function returns the handle for the filesystem
       in(1,8) which the object referenced by the handle given by the hanp and hlen
       arguments resides.

       The open_by_handle() function opens a file(1,n) descriptor  for  the  object
       referenced  by a handle.  It is analogous and identical to open(2,3,n)(2) with
       the exception of accepting handles instead of path names.

       The readlink_by_handle() function returns the contents  of  a  symbolic
       link(1,2) 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(1,n)
       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(1,n)
       descriptor.

       The  fssetdm_by_handle()  function  sets the di_dmevmask and di_dmstate
       fields in(1,8) 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,3,n)(2), readlink(1,2)(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(3,n) they succeed; other-
       wise, they return the value -1 and set(7,n,1 builtins) errno to indicate the error:


       [EACCES]       Search permission was denied for a component of path.

       [EBADF]        fd is not a valid and open(2,3,n) file(1,n) descriptor.

       [EFAULT]       An argument pointed to an invalid address.

       [EINVAL]       path is in(1,8) a filesystem  that  does  not  support  these
                      functions.

       [ELOOP]        Too  many symbolic links were encountered in(1,8) 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)

References for this manual (incoming links)