1HANDLE(3)                  Library Functions Manual                  HANDLE(3)
2
3
4

NAME

6       path_to_handle,   path_to_fshandle,  fd_to_handle,  handle_to_fshandle,
7       open_by_handle,        readlink_by_handle,        attr_multi_by_handle,
8       attr_list_by_handle, fssetdm_by_handle, free_handle, getparents_by_han‐
9       dle, getparentpaths_by_handle - file handle operations
10

C SYNOPSIS

12       #include <sys/types.h>
13       #include <xfs/handle.h>
14
15       int path_to_handle(char *path, void **hanp, size_t *hlen);
16
17       int path_to_fshandle(char *path, void **hanp, size_t *hlen);
18
19       int fd_to_handle(int fd, void **hanp, size_t *hlen);
20
21       int handle_to_fshandle(void *hanp, size_t hlen, void  **fshanp,  size_t
22              *fshlen);
23
24       int open_by_handle(void *hanp, size_t hlen, int oflag);
25
26       int readlink_by_handle(void *hanp, size_t hlen, void *buf, size_t bs);
27
28       int attr_multi_by_handle(void   *hanp,  size_t  hlen,  void  *buf,  int
29              rtrvcnt, int flags);
30
31       int attr_list_by_handle(void *hanp, size_t hlen, char *buf, size_t buf‐
32              siz, int flags, struct attrlist_cursor *cursor);
33
34       int fssetdm_by_handle(void   *hanp,   size_t   hlen,  struct  fsdmidata
35              *fssetdm);
36
37       void free_handle(void *hanp, size_t hlen);
38
39       int getparents_by_handle(void *hanp, size_t hlen, parent_t *buf, size_t
40              bufsiz,  parent_cursor_t  *cursor, unsigned int *count, unsigned
41              int *more);
42
43       int getparentpaths_by_handle(void *hanp, size_t  hlen,  parent_t  *buf,
44              size_t  bufsiz,  parent_cursor_t  *cursor,  unsigned int *count,
45              unsigned int *more);
46

DESCRIPTION

48       These functions provide a way to perform certain filesystem  operations
49       without  using a file descriptor to access filesystem objects. They are
50       intended for use by a limited set of system utilities  such  as  backup
51       programs. They are supported only by the XFS filesystem.  Link with the
52       libhandle library to access these functions.
53
54       A handle, hanp, uniquely identifies a filesystem object  or  an  entire
55       filesystem.   There  is  one  and  only  one  handle  per filesystem or
56       filesystem object.  Handles consist of some number of bytes.  The  size
57       of a handle (i.e. the number of bytes comprising it) varies by the type
58       of handle and may vary for different objects of  the  same  type.   The
59       content of a handle is opaque to applications.  Since handle sizes vary
60       and their contents are opaque, handles are described by two quantities,
61       a pointer (hanp) and a size (hlen).  The size, hlen, indicates the num‐
62       ber of bytes in the handle which are pointed to by the pointer.
63
64       The path_to_handle() function returns the handle for the  object  given
65       by the path argument. If the final component of the path name is a sym‐
66       bolic link, the handle returned is that of the link itself.
67
68       The path_to_fshandle() function returns the handle for  the  filesystem
69       in which the object given by the path argument resides.
70
71       The  fd_to_handle()  function  returns the handle for the object refer‐
72       enced by the fd argument, which must be a valid file descriptor.
73
74       The handle_to_fshandle() function returns the handle for the filesystem
75       in which the object referenced by the handle given by the hanp and hlen
76       arguments resides.
77
78       The open_by_handle() function opens a file descriptor  for  the  object
79       referenced  by a handle.  It is analogous and identical to open(2) with
80       the exception of accepting handles instead of path names.
81
82       The readlink_by_handle() function returns the contents  of  a  symbolic
83       link referenced by a handle.
84
85       The   attr_multi_by_handle()   function   manipulates   multiple   user
86       attributes on a filesystem object.  It is analogous  and  identical  to
87       attr_multif(3)  except  that  a  handle  is specified instead of a file
88       descriptor.
89
90       The attr_list_by_handle()  function  returns  the  names  of  the  user
91       attributes  of  a  filesystem object.  It is analogous and identical to
92       attr_listf(3) except that a handle  is  specified  instead  of  a  file
93       descriptor.
94
95       The  fssetdm_by_handle()  function  sets the di_dmevmask and di_dmstate
96       fields in an XFS on-disk inode. It is analogous to the  XFS_IOC_FSSETDM
97       xfsctl(3) command, except that a handle is specified instead of a file.
98
99       The  free_handle()  function  frees  the  storage allocated for handles
100       returned by the following functions:  path_to_handle(),  path_to_fshan‐
101       dle(), fd_to_handle(), and handle_to_fshandle().
102
103       The getparents_by_handle() function returns an array of parent_t struc‐
104       tures for each hardlink to the inode represented by the  given  handle.
105       The parent structure encodes the parent inode number, generation number
106       and the basename of the link.  This  function  is  not  operational  on
107       Linux.
108
109       The  getparentpaths_by_handle()  function  is  identical to the getpar‐
110       ents_by_handle() function except that instead of returning the basename
111       it  returns  the path of the link up to the mount point.  This function
112       is also not operational on Linux.
113

RETURN VALUE

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

ERRORS

120       EACCES Search permission was denied for a component of path.
121
122       EBADF  fd is not a valid and open file descriptor.
123
124       EFAULT An argument pointed to an invalid address.
125
126       EINVAL path is in a filesystem that does not support these functions.
127
128       ELOOP  Too many symbolic links were encountered in translating the path
129              name.
130
131       ENAMETOOLONG
132              A  component  of  path  or  the  entire  length  of path exceeds
133              filesystem limits.
134
135       ENOENT A component of path does not exist.
136
137       EPERM  The caller does not have sufficient privileges.
138

SEE ALSO

140       open(2), readlink(2), attr_multi(3), attr_list(3), xfsctl(3), xfs(5).
141
142
143
144                                                                     HANDLE(3)
Impressum