1HANDLE(3) Library Functions Manual HANDLE(3)
2
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
12 #include <sys/types.h>
13 #include <xfs/handle.h>
14 int path_to_handle(char *path, void **hanp, size_t *hlen);
16 int path_to_fshandle(char *path, void **hanp, size_t *hlen);
18 int fd_to_handle(int fd, void **hanp, size_t *hlen);
20 int handle_to_fshandle(void *hanp, size_t hlen, void **fshanp, size_t
22 *fshlen);
23 int open_by_handle(void *hanp, size_t hlen, int oflag);
25 int readlink_by_handle(void *hanp, size_t hlen, void *buf, size_t bs);
27 int attr_multi_by_handle(void *hanp, size_t hlen, void *buf, int
29 rtrvcnt, int flags);
30 int attr_list_by_handle(void *hanp, size_t hlen, char *buf, size_t buf‐
32 siz, int flags, struct attrlist_cursor *cursor);
33 int fssetdm_by_handle(void *hanp, size_t hlen, struct fsdmidata *fs‐
35 setdm);
36 void free_handle(void *hanp, size_t hlen);
38 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 int getparentpaths_by_handle(void *hanp, size_t hlen, parent_t *buf,
44 size_t bufsiz, parent_cursor_t *cursor, unsigned int *count, un‐
45 signed int *more);
46
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 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 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 The path_to_fshandle() function returns the handle for the filesystem
69 in which the object given by the path argument resides.
70 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 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 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 The readlink_by_handle() function returns the contents of a symbolic
83 link referenced by a handle.
84 The attr_multi_by_handle() function manipulates multiple user at‐
86 tributes on a filesystem object. It is analogous and identical to
87 attr_multif(3) except that a handle is specified instead of a file de‐
88 scriptor.
89 The attr_list_by_handle() function returns the names of the user at‐
91 tributes of a filesystem object. It is analogous and identical to
92 attr_listf(3) except that a handle is specified instead of a file de‐
93 scriptor.
94 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 This function is not supported on Linux.
99 The free_handle() function frees the storage allocated for handles re‐
101 turned by the following functions: path_to_handle(), path_to_fshan‐
102 dle(), fd_to_handle(), and handle_to_fshandle().
103 The getparents_by_handle() function returns an array of parent_t struc‐
105 tures for each hardlink to the inode represented by the given handle.
106 The parent structure encodes the parent inode number, generation number
107 and the basename of the link. This function is not operational on
108 Linux.
109 The getparentpaths_by_handle() function is identical to the getpar‐
111 ents_by_handle() function except that instead of returning the basename
112 it returns the path of the link up to the mount point. This function
113 is also not operational on Linux.
114
116 The function free_handle() has no failure indication. The other func‐
117 tions return the value 0 to the calling process if they succeed; other‐
118 wise, they return the value -1 and set errno to indicate the error.
119
121 EACCES Search permission was denied for a component of path.
122 EBADF fd is not a valid and open file descriptor.
124 EFAULT An argument pointed to an invalid address.
126 EINVAL path is in a filesystem that does not support these functions.
128 ELOOP Too many symbolic links were encountered in translating the path
130 name.
131 ENAMETOOLONG
133 A component of path or the entire length of path exceeds
134 filesystem limits.
135 ENOENT A component of path does not exist.
137 EPERM The caller does not have sufficient privileges.
139
141 open(2), readlink(2), attr_multi(3), attr_list(3), xfsctl(3), xfs(5).
142 HANDLE(3)