1open_by_handle_at(2) System Calls Manual open_by_handle_at(2)
2
6 name_to_handle_at, open_by_handle_at - obtain handle for a pathname and
7 open file via a handle
8
10 Standard C library (libc, -lc)
11
13 #define _GNU_SOURCE /* See feature_test_macros(7) */
14 #include <fcntl.h>
15 int name_to_handle_at(int dirfd, const char *pathname,
17 struct file_handle *handle,
18 int *mount_id, int flags);
19 int open_by_handle_at(int mount_fd, struct file_handle *handle,
20 int flags);
21
23 The name_to_handle_at() and open_by_handle_at() system calls split the
24 functionality of openat(2) into two parts: name_to_handle_at() returns
25 an opaque handle that corresponds to a specified file; open_by_han‐
26 dle_at() opens the file corresponding to a handle returned by a previ‐
27 ous call to name_to_handle_at() and returns an open file descriptor.
28 name_to_handle_at()
30 The name_to_handle_at() system call returns a file handle and a mount
31 ID corresponding to the file specified by the dirfd and pathname argu‐
32 ments. The file handle is returned via the argument handle, which is a
33 pointer to a structure of the following form:
34 struct file_handle {
36 unsigned int handle_bytes; /* Size of f_handle [in, out] */
37 int handle_type; /* Handle type [out] */
38 unsigned char f_handle[0]; /* File identifier (sized by
39 caller) [out] */
40 };
41 It is the caller's responsibility to allocate the structure with a size
43 large enough to hold the handle returned in f_handle. Before the call,
44 the handle_bytes field should be initialized to contain the allocated
45 size for f_handle. (The constant MAX_HANDLE_SZ, defined in <fcntl.h>,
46 specifies the maximum expected size for a file handle. It is not a
47 guaranteed upper limit as future filesystems may require more space.)
48 Upon successful return, the handle_bytes field is updated to contain
49 the number of bytes actually written to f_handle.
50 The caller can discover the required size for the file_handle structure
52 by making a call in which handle->handle_bytes is zero; in this case,
53 the call fails with the error EOVERFLOW and handle->handle_bytes is set
54 to indicate the required size; the caller can then use this information
55 to allocate a structure of the correct size (see EXAMPLES below). Some
56 care is needed here as EOVERFLOW can also indicate that no file handle
57 is available for this particular name in a filesystem which does nor‐
58 mally support file-handle lookup. This case can be detected when the
59 EOVERFLOW error is returned without handle_bytes being increased.
60 Other than the use of the handle_bytes field, the caller should treat
62 the file_handle structure as an opaque data type: the handle_type and
63 f_handle fields are needed only by a subsequent call to open_by_han‐
64 dle_at().
65 The flags argument is a bit mask constructed by ORing together zero or
67 more of AT_EMPTY_PATH and AT_SYMLINK_FOLLOW, described below.
68 Together, the pathname and dirfd arguments identify the file for which
70 a handle is to be obtained. There are four distinct cases:
71 • If pathname is a nonempty string containing an absolute pathname,
73 then a handle is returned for the file referred to by that pathname.
74 In this case, dirfd is ignored.
75 • If pathname is a nonempty string containing a relative pathname and
77 dirfd has the special value AT_FDCWD, then pathname is interpreted
78 relative to the current working directory of the caller, and a han‐
79 dle is returned for the file to which it refers.
80 • If pathname is a nonempty string containing a relative pathname and
82 dirfd is a file descriptor referring to a directory, then pathname
83 is interpreted relative to the directory referred to by dirfd, and a
84 handle is returned for the file to which it refers. (See openat(2)
85 for an explanation of why "directory file descriptors" are useful.)
86 • If pathname is an empty string and flags specifies the value
88 AT_EMPTY_PATH, then dirfd can be an open file descriptor referring
89 to any type of file, or AT_FDCWD, meaning the current working direc‐
90 tory, and a handle is returned for the file to which it refers.
91 The mount_id argument returns an identifier for the filesystem mount
93 that corresponds to pathname. This corresponds to the first field in
94 one of the records in /proc/self/mountinfo. Opening the pathname in
95 the fifth field of that record yields a file descriptor for the mount
96 point; that file descriptor can be used in a subsequent call to
97 open_by_handle_at(). mount_id is returned both for a successful call
98 and for a call that results in the error EOVERFLOW.
99 By default, name_to_handle_at() does not dereference pathname if it is
101 a symbolic link, and thus returns a handle for the link itself. If
102 AT_SYMLINK_FOLLOW is specified in flags, pathname is dereferenced if it
103 is a symbolic link (so that the call returns a handle for the file re‐
104 ferred to by the link).
105 name_to_handle_at() does not trigger a mount when the final component
107 of the pathname is an automount point. When a filesystem supports both
108 file handles and automount points, a name_to_handle_at() call on an au‐
109 tomount point will return with error EOVERFLOW without having increased
110 handle_bytes. This can happen since Linux 4.13 with NFS when accessing
111 a directory which is on a separate filesystem on the server. In this
112 case, the automount can be triggered by adding a "/" to the end of the
113 pathname.
114 open_by_handle_at()
116 The open_by_handle_at() system call opens the file referred to by han‐
117 dle, a file handle returned by a previous call to name_to_handle_at().
118 The mount_fd argument is a file descriptor for any object (file, direc‐
120 tory, etc.) in the mounted filesystem with respect to which handle
121 should be interpreted. The special value AT_FDCWD can be specified,
122 meaning the current working directory of the caller.
123 The flags argument is as for open(2). If handle refers to a symbolic
125 link, the caller must specify the O_PATH flag, and the symbolic link is
126 not dereferenced; the O_NOFOLLOW flag, if specified, is ignored.
127 The caller must have the CAP_DAC_READ_SEARCH capability to invoke
129 open_by_handle_at().
130
132 On success, name_to_handle_at() returns 0, and open_by_handle_at() re‐
133 turns a file descriptor (a nonnegative integer).
134 In the event of an error, both system calls return -1 and set errno to
136 indicate the error.
137
139 name_to_handle_at() and open_by_handle_at() can fail for the same er‐
140 rors as openat(2). In addition, they can fail with the errors noted
141 below.
142 name_to_handle_at() can fail with the following errors:
144 EFAULT pathname, mount_id, or handle points outside your accessible ad‐
146 dress space.
147 EINVAL flags includes an invalid bit value.
149 EINVAL handle->handle_bytes is greater than MAX_HANDLE_SZ.
151 ENOENT pathname is an empty string, but AT_EMPTY_PATH was not specified
153 in flags.
154 ENOTDIR
156 The file descriptor supplied in dirfd does not refer to a direc‐
157 tory, and it is not the case that both flags includes
158 AT_EMPTY_PATH and pathname is an empty string.
159 EOPNOTSUPP
161 The filesystem does not support decoding of a pathname to a file
162 handle.
163 EOVERFLOW
165 The handle->handle_bytes value passed into the call was too
166 small. When this error occurs, handle->handle_bytes is updated
167 to indicate the required size for the handle.
168 open_by_handle_at() can fail with the following errors:
170 EBADF mount_fd is not an open file descriptor.
172 EBADF pathname is relative but dirfd is neither AT_FDCWD nor a valid
174 file descriptor.
175 EFAULT handle points outside your accessible address space.
177 EINVAL handle->handle_bytes is greater than MAX_HANDLE_SZ or is equal
179 to zero.
180 ELOOP handle refers to a symbolic link, but O_PATH was not specified
182 in flags.
183 EPERM The caller does not have the CAP_DAC_READ_SEARCH capability.
185 ESTALE The specified handle is not valid. This error will occur if,
187 for example, the file has been deleted.
188
190 FreeBSD has a broadly similar pair of system calls in the form of
191 getfh() and openfh().
192
194 Linux.
195
197 Linux 2.6.39, glibc 2.14.
198
200 A file handle can be generated in one process using name_to_handle_at()
201 and later used in a different process that calls open_by_handle_at().
202 Some filesystem don't support the translation of pathnames to file han‐
204 dles, for example, /proc, /sys, and various network filesystems.
205 A file handle may become invalid ("stale") if a file is deleted, or for
207 other filesystem-specific reasons. Invalid handles are notified by an
208 ESTALE error from open_by_handle_at().
209 These system calls are designed for use by user-space file servers.
211 For example, a user-space NFS server might generate a file handle and
212 pass it to an NFS client. Later, when the client wants to open the
213 file, it could pass the handle back to the server. This sort of func‐
214 tionality allows a user-space file server to operate in a stateless
215 fashion with respect to the files it serves.
216 If pathname refers to a symbolic link and flags does not specify
218 AT_SYMLINK_FOLLOW, then name_to_handle_at() returns a handle for the
219 link (rather than the file to which it refers). The process receiving
220 the handle can later perform operations on the symbolic link by con‐
221 verting the handle to a file descriptor using open_by_handle_at() with
222 the O_PATH flag, and then passing the file descriptor as the dirfd ar‐
223 gument in system calls such as readlinkat(2) and fchownat(2).
224 Obtaining a persistent filesystem ID
226 The mount IDs in /proc/self/mountinfo can be reused as filesystems are
227 unmounted and mounted. Therefore, the mount ID returned by
228 name_to_handle_at() (in *mount_id) should not be treated as a persis‐
229 tent identifier for the corresponding mounted filesystem. However, an
230 application can use the information in the mountinfo record that corre‐
231 sponds to the mount ID to derive a persistent identifier.
232 For example, one can use the device name in the fifth field of the
234 mountinfo record to search for the corresponding device UUID via the
235 symbolic links in /dev/disks/by-uuid. (A more comfortable way of ob‐
236 taining the UUID is to use the libblkid(3) library.) That process can
237 then be reversed, using the UUID to look up the device name, and then
238 obtaining the corresponding mount point, in order to produce the
239 mount_fd argument used by open_by_handle_at().
240
242 The two programs below demonstrate the use of name_to_handle_at() and
243 open_by_handle_at(). The first program (t_name_to_handle_at.c) uses
244 name_to_handle_at() to obtain the file handle and mount ID for the file
245 specified in its command-line argument; the handle and mount ID are
246 written to standard output.
247 The second program (t_open_by_handle_at.c) reads a mount ID and file
249 handle from standard input. The program then employs open_by_han‐
250 dle_at() to open the file using that handle. If an optional command-
251 line argument is supplied, then the mount_fd argument for open_by_han‐
252 dle_at() is obtained by opening the directory named in that argument.
253 Otherwise, mount_fd is obtained by scanning /proc/self/mountinfo to
254 find a record whose mount ID matches the mount ID read from standard
255 input, and the mount directory specified in that record is opened.
256 (These programs do not deal with the fact that mount IDs are not per‐
257 sistent.)
258 The following shell session demonstrates the use of these two programs:
260 $ echo 'Can you please think about it?' > cecilia.txt
262 $ ./t_name_to_handle_at cecilia.txt > fh
263 $ ./t_open_by_handle_at < fh
264 open_by_handle_at: Operation not permitted
265 $ sudo ./t_open_by_handle_at < fh # Need CAP_SYS_ADMIN
266 Read 31 bytes
267 $ rm cecilia.txt
268 Now we delete and (quickly) re-create the file so that it has the same
270 content and (by chance) the same inode. Nevertheless, open_by_han‐
271 dle_at() recognizes that the original file referred to by the file han‐
272 dle no longer exists.
273 $ stat --printf="%i\n" cecilia.txt # Display inode number
275 4072121
276 $ rm cecilia.txt
277 $ echo 'Can you please think about it?' > cecilia.txt
278 $ stat --printf="%i\n" cecilia.txt # Check inode number
279 4072121
280 $ sudo ./t_open_by_handle_at < fh
281 open_by_handle_at: Stale NFS file handle
282 Program source: t_name_to_handle_at.c
284 #define _GNU_SOURCE
286 #include <err.h>
287 #include <errno.h>
288 #include <fcntl.h>
289 #include <stdio.h>
290 #include <stdlib.h>
291 int
293 main(int argc, char *argv[])
294 {
295 int mount_id, fhsize, flags, dirfd;
296 char *pathname;
297 struct file_handle *fhp;
298 if (argc != 2) {
300 fprintf(stderr, "Usage: %s pathname\n", argv[0]);
301 exit(EXIT_FAILURE);
302 }
303 pathname = argv[1];
305 /* Allocate file_handle structure. */
307 fhsize = sizeof(*fhp);
309 fhp = malloc(fhsize);
310 if (fhp == NULL)
311 err(EXIT_FAILURE, "malloc");
312 /* Make an initial call to name_to_handle_at() to discover
314 the size required for file handle. */
315 dirfd = AT_FDCWD; /* For name_to_handle_at() calls */
317 flags = 0; /* For name_to_handle_at() calls */
318 fhp->handle_bytes = 0;
319 if (name_to_handle_at(dirfd, pathname, fhp,
320 &mount_id, flags) != -1
321 || errno != EOVERFLOW)
322 {
323 fprintf(stderr, "Unexpected result from name_to_handle_at()\n");
324 exit(EXIT_FAILURE);
325 }
326 /* Reallocate file_handle structure with correct size. */
328 fhsize = sizeof(*fhp) + fhp->handle_bytes;
330 fhp = realloc(fhp, fhsize); /* Copies fhp->handle_bytes */
331 if (fhp == NULL)
332 err(EXIT_FAILURE, "realloc");
333 /* Get file handle from pathname supplied on command line. */
335 if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1)
337 err(EXIT_FAILURE, "name_to_handle_at");
338 /* Write mount ID, file handle size, and file handle to stdout,
340 for later reuse by t_open_by_handle_at.c. */
341 printf("%d\n", mount_id);
343 printf("%u %d ", fhp->handle_bytes, fhp->handle_type);
344 for (size_t j = 0; j < fhp->handle_bytes; j++)
345 printf(" %02x", fhp->f_handle[j]);
346 printf("\n");
347 exit(EXIT_SUCCESS);
349 }
350 Program source: t_open_by_handle_at.c
352 #define _GNU_SOURCE
354 #include <err.h>
355 #include <fcntl.h>
356 #include <limits.h>
357 #include <stdio.h>
358 #include <stdlib.h>
359 #include <string.h>
360 #include <unistd.h>
361 /* Scan /proc/self/mountinfo to find the line whose mount ID matches
363 'mount_id'. (An easier way to do this is to install and use the
364 'libmount' library provided by the 'util-linux' project.)
365 Open the corresponding mount path and return the resulting file
366 descriptor. */
367 static int
369 open_mount_path_by_id(int mount_id)
370 {
371 int mi_mount_id, found;
372 char mount_path[PATH_MAX];
373 char *linep;
374 FILE *fp;
375 size_t lsize;
376 ssize_t nread;
377 fp = fopen("/proc/self/mountinfo", "r");
379 if (fp == NULL)
380 err(EXIT_FAILURE, "fopen");
381 found = 0;
383 linep = NULL;
384 while (!found) {
385 nread = getline(&linep, &lsize, fp);
386 if (nread == -1)
387 break;
388 nread = sscanf(linep, "%d %*d %*s %*s %s",
390 &mi_mount_id, mount_path);
391 if (nread != 2) {
392 fprintf(stderr, "Bad sscanf()\n");
393 exit(EXIT_FAILURE);
394 }
395 if (mi_mount_id == mount_id)
397 found = 1;
398 }
399 free(linep);
400 fclose(fp);
402 if (!found) {
404 fprintf(stderr, "Could not find mount point\n");
405 exit(EXIT_FAILURE);
406 }
407 return open(mount_path, O_RDONLY);
409 }
410 int
412 main(int argc, char *argv[])
413 {
414 int mount_id, fd, mount_fd, handle_bytes;
415 char buf[1000];
416 #define LINE_SIZE 100
417 char line1[LINE_SIZE], line2[LINE_SIZE];
418 char *nextp;
419 ssize_t nread;
420 struct file_handle *fhp;
421 if ((argc > 1 && strcmp(argv[1], "--help") == 0) || argc > 2) {
423 fprintf(stderr, "Usage: %s [mount-path]\n", argv[0]);
424 exit(EXIT_FAILURE);
425 }
426 /* Standard input contains mount ID and file handle information:
428 Line 1: <mount_id>
430 Line 2: <handle_bytes> <handle_type> <bytes of handle in hex>
431 */
432 if (fgets(line1, sizeof(line1), stdin) == NULL ||
434 fgets(line2, sizeof(line2), stdin) == NULL)
435 {
436 fprintf(stderr, "Missing mount_id / file handle\n");
437 exit(EXIT_FAILURE);
438 }
439 mount_id = atoi(line1);
441 handle_bytes = strtoul(line2, &nextp, 0);
443 /* Given handle_bytes, we can now allocate file_handle structure. */
445 fhp = malloc(sizeof(*fhp) + handle_bytes);
447 if (fhp == NULL)
448 err(EXIT_FAILURE, "malloc");
449 fhp->handle_bytes = handle_bytes;
451 fhp->handle_type = strtoul(nextp, &nextp, 0);
453 for (size_t j = 0; j < fhp->handle_bytes; j++)
455 fhp->f_handle[j] = strtoul(nextp, &nextp, 16);
456 /* Obtain file descriptor for mount point, either by opening
458 the pathname specified on the command line, or by scanning
459 /proc/self/mounts to find a mount that matches the 'mount_id'
460 that we received from stdin. */
461 if (argc > 1)
463 mount_fd = open(argv[1], O_RDONLY);
464 else
465 mount_fd = open_mount_path_by_id(mount_id);
466 if (mount_fd == -1)
468 err(EXIT_FAILURE, "opening mount fd");
469 /* Open file using handle and mount point. */
471 fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);
473 if (fd == -1)
474 err(EXIT_FAILURE, "open_by_handle_at");
475 /* Try reading a few bytes from the file. */
477 nread = read(fd, buf, sizeof(buf));
479 if (nread == -1)
480 err(EXIT_FAILURE, "read");
481 printf("Read %zd bytes\n", nread);
483 exit(EXIT_SUCCESS);
485 }
486
488 open(2), libblkid(3), blkid(8), findfs(8), mount(8)
489 The libblkid and libmount documentation in the latest util-linux re‐
491 lease at ⟨https://www.kernel.org/pub/linux/utils/util-linux/⟩
492Linux man-pages 6.05 2023-05-03 open_by_handle_at(2)