Debian Codegraph @

upstream/debian-unstable/man2/open_by_handle_at.2

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH open_by_handle_at 2 2026-02-22 "Linux man-pages 6.18"
7 .SH NAME
8 name_to_handle_at, open_by_handle_at \- obtain handle
9 for a pathname and open file via a handle
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .B #include <fcntl.h>
17 .P
18 .BI "int name_to_handle_at(int " dirfd ", const char *" path ,
19 .BI " struct file_handle *" handle ,
20 .BI " int *" mount_id ", int " flags );
21 .BI "int open_by_handle_at(int " mount_fd ", struct file_handle *" handle ,
22 .BI " int " flags );
23 .fi
24 .SH DESCRIPTION
25 The
26 .BR name_to_handle_at ()
27 and
28 .BR open_by_handle_at ()
29 system calls split the functionality of
30 .BR openat (2)
31 into two parts:
32 .BR name_to_handle_at ()
33 returns an opaque handle that corresponds to a specified file;
34 .BR open_by_handle_at ()
35 opens the file corresponding to a handle returned by a previous call to
36 .BR name_to_handle_at ()
37 and returns an open file descriptor.
38 .\"
39 .\"
40 .SS name_to_handle_at()
41 The
42 .BR name_to_handle_at ()
43 system call returns a file handle and a mount ID corresponding to
44 the file specified by the
45 .I dirfd
46 and
47 .I path
48 arguments.
49 The file handle is returned via the argument
50 .IR handle ,
51 which is a pointer to a structure of the following form:
52 .P
53 .in +4n
54 .EX
55 struct file_handle {
56 unsigned int handle_bytes; /* Size of f_handle [in, out] */
57 int handle_type; /* Handle type [out] */
58 unsigned char f_handle[0]; /* File identifier (sized by
59 caller) [out] */
60 };
61 .EE
62 .in
63 .P
64 It is the caller's responsibility to allocate the structure
65 with a size large enough to hold the handle returned in
66 .IR f_handle .
67 Before the call, the
68 .I handle_bytes
69 field should be initialized to contain the allocated size for
70 .IR f_handle .
71 (The constant
72 .BR MAX_HANDLE_SZ ,
73 defined in
74 .IR <fcntl.h> ,
75 specifies the maximum expected size for a file handle.
76 It is not a
77 guaranteed upper limit as future filesystems may require more space.)
78 Upon successful return, the
79 .I handle_bytes
80 field is updated to contain the number of bytes actually written to
81 .IR f_handle .
82 .P
83 The caller can discover the required size for the
84 .I file_handle
85 structure by making a call in which
86 .I handle\->handle_bytes
87 is zero;
88 in this case, the call fails with the error
89 .B EOVERFLOW
90 and
91 .I handle\->handle_bytes
92 is set to indicate the required size;
93 the caller can then use this information to allocate a structure
94 of the correct size (see EXAMPLES below).
95 Some care is needed here as
96 .B EOVERFLOW
97 can also indicate that no file handle is available for this particular
98 name in a filesystem which does normally support file-handle lookup.
99 This case can be detected when the
100 .B EOVERFLOW
101 error is returned without
102 .I handle_bytes
103 being increased.
104 .P
105 Other than the use of the
106 .I handle_bytes
107 field, the caller should treat the
108 .I file_handle
109 structure as an opaque data type: the
110 .I handle_type
111 and
112 .I f_handle
113 fields can be used in a subsequent call to
114 .BR open_by_handle_at ().
115 The caller can also use the opaque
116 .I file_handle
117 to compare the identity of filesystem objects
118 that were queried at different times and possibly
119 at different paths.
120 The
121 .BR fanotify (7)
122 subsystem can report events
123 with an information record containing a
124 .I file_handle
125 to identify the filesystem object.
126 .P
127 The
128 .I flags
129 argument is a bit mask constructed by ORing together zero or more of
130 .BR AT_HANDLE_FID ,
131 .BR AT_HANDLE_MNT_ID_UNIQUE ,
132 .BR AT_HANDLE_CONNECTABLE ,
133 .BR AT_EMPTY_PATH ,
134 and
135 .BR AT_SYMLINK_FOLLOW ,
136 described below.
137 .P
138 When
139 .I flags
140 contain the
141 .BR AT_HANDLE_FID " (since Linux 6.5)"
142 .\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
143 flag, the caller indicates that the returned
144 .I file_handle
145 is needed to identify the filesystem object,
146 and not for opening the file later,
147 so it should be expected that a subsequent call to
148 .BR open_by_handle_at ()
149 with the returned
150 .I file_handle
151 may fail.
152 .P
153 When
154 .I flags
155 contain the
156 .BR AT_HANDLE_MNT_ID_UNIQUE " (since Linux 6.12)"
157 .\" commit 4356d575ef0f39a3e8e0ce0c40d84ce900ac3b61
158 flag, the caller indicates that the width of the
159 .I mount_id
160 buffer is at least 64 bits,
161 and then the mount id returned in that buffer
162 is the unique mount id as the one returned by
163 .BR statx (2)
164 with the
165 .B STATX_MNT_ID_UNIQUE
166 flag.
167 .P
168 When
169 .I flags
170 contain the
171 .BR AT_HANDLE_CONNECTABLE " (since Linux 6.13)"
172 .\" commit a20853ab8296d4a8754482cb5e9adde8ab426a25
173 flag, the caller indicates that the returned
174 .I file_handle
175 is needed to open a file with known path later,
176 so it should be expected that a subsequent call to
177 .BR open_by_handle_at ()
178 with the returned
179 .I file_handle
180 may fail if the file was moved,
181 but otherwise,
182 the path of the opened file is expected to be visible
183 from the
184 .IR /proc/ pid /fd/ *
185 magic link.
186 This flag can not be used in combination with the flags
187 .B AT_HANDLE_FID
188 and/or
189 .BR AT_EMPTY_PATH .
190 .P
191 Together, the
192 .I path
193 and
194 .I dirfd
195 arguments identify the file for which a handle is to be obtained.
196 There are four distinct cases:
197 .IP \[bu] 3
198 If
199 .I path
200 is a nonempty string containing an absolute pathname,
201 then a handle is returned for the file referred to by that pathname.
202 In this case,
203 .I dirfd
204 is ignored.
205 .IP \[bu]
206 If
207 .I path
208 is a nonempty string containing a relative pathname and
209 .I dirfd
210 has the special value
211 .BR AT_FDCWD ,
212 then
213 .I path
214 is interpreted relative to the current working directory of the caller,
215 and a handle is returned for the file to which it refers.
216 .IP \[bu]
217 If
218 .I path
219 is a nonempty string containing a relative pathname and
220 .I dirfd
221 is a file descriptor referring to a directory, then
222 .I path
223 is interpreted relative to the directory referred to by
224 .IR dirfd ,
225 and a handle is returned for the file to which it refers.
226 (See
227 .BR openat (2)
228 for an explanation of why "directory file descriptors" are useful.)
229 .IP \[bu]
230 If
231 .I path
232 is an empty string and
233 .I flags
234 specifies the value
235 .BR AT_EMPTY_PATH ,
236 then
237 .I dirfd
238 can be an open file descriptor referring to any type of file,
239 or
240 .BR AT_FDCWD ,
241 meaning the current working directory,
242 and a handle is returned for the file to which it refers.
243 .P
244 The
245 .I mount_id
246 argument returns an identifier for the filesystem
247 mount that corresponds to
248 .IR path .
249 This corresponds to the first field in one of the records in
250 .IR /proc/self/mountinfo .
251 Opening the pathname in the fifth field of that record yields a file
252 descriptor for the mount point;
253 that file descriptor can be used in a subsequent call to
254 .BR open_by_handle_at ().
255 .I mount_id
256 is returned both for a successful call and for a call that results
257 in the error
258 .BR EOVERFLOW .
259 .P
260 By default,
261 .BR name_to_handle_at ()
262 does not dereference
263 .I path
264 if it is a symbolic link, and thus returns a handle for the link itself.
265 If
266 .B AT_SYMLINK_FOLLOW
267 is specified in
268 .IR flags ,
269 .I path
270 is dereferenced if it is a symbolic link
271 (so that the call returns a handle for the file referred to by the link).
272 .P
273 .BR name_to_handle_at ()
274 does not trigger a mount when the final component of the pathname is an
275 automount point.
276 When a filesystem supports both file handles and
277 automount points, a
278 .BR name_to_handle_at ()
279 call on an automount point will return with error
280 .B EOVERFLOW
281 without having increased
282 .IR handle_bytes .
283 This can happen since Linux 4.13
284 .\" commit 20fa19027286983ab2734b5910c4a687436e0c31
285 with NFS when accessing a directory
286 which is on a separate filesystem on the server.
287 In this case, the automount can be triggered by adding a "/" to the end
288 of the pathname.
289 .SS open_by_handle_at()
290 The
291 .BR open_by_handle_at ()
292 system call opens the file referred to by
293 .IR handle ,
294 a file handle returned by a previous call to
295 .BR name_to_handle_at ().
296 .P
297 The
298 .I mount_fd
299 argument is a file descriptor for any object (file, directory, etc.)
300 in the mounted filesystem with respect to which
301 .I handle
302 should be interpreted.
303 The special value
304 .B AT_FDCWD
305 can be specified, meaning the current working directory of the caller.
306 .P
307 The
308 .I flags
309 argument
310 is as for
311 .BR open (2).
312 If
313 .I handle
314 refers to a symbolic link,
315 the caller must specify the
316 .B O_PATH
317 flag,
318 and the symbolic link is not dereferenced;
319 the
320 .B O_NOFOLLOW
321 flag,
322 if specified,
323 is ignored.
324 .P
325 The caller must have the
326 .B CAP_DAC_READ_SEARCH
327 capability to invoke
328 .BR open_by_handle_at ().
329 .SH RETURN VALUE
330 On success,
331 .BR name_to_handle_at ()
332 returns 0,
333 and
334 .BR open_by_handle_at ()
335 returns a file descriptor (a nonnegative integer).
336 .P
337 In the event of an error, both system calls return \-1 and set
338 .I errno
339 to indicate the error.
340 .SH ERRORS
341 .BR name_to_handle_at ()
342 and
343 .BR open_by_handle_at ()
344 can fail for the same errors as
345 .BR openat (2).
346 In addition, they can fail with the errors noted below.
347 .P
348 .BR name_to_handle_at ()
349 can fail with the following errors:
350 .TP
351 .B EFAULT
352 .IR path ,
353 .IR mount_id ,
354 or
355 .I handle
356 points outside your accessible address space.
357 .TP
358 .B EINVAL
359 .I flags
360 includes an invalid bit value or an invalid bit combination.
361 .TP
362 .B EINVAL
363 .I handle\->handle_bytes
364 is greater than
365 .BR MAX_HANDLE_SZ .
366 .TP
367 .B ENOENT
368 .I path
369 is an empty string, but
370 .B AT_EMPTY_PATH
371 was not specified in
372 .IR flags .
373 .TP
374 .B ENOTDIR
375 The file descriptor supplied in
376 .I dirfd
377 does not refer to a directory,
378 and it is not the case that both
379 .I flags
380 includes
381 .B AT_EMPTY_PATH
382 and
383 .I path
384 is an empty string.
385 .TP
386 .B EOPNOTSUPP
387 The filesystem does not support decoding of a pathname to a file handle.
388 .TP
389 .B EOVERFLOW
390 The
391 .I handle\->handle_bytes
392 value passed into the call was too small.
393 When this error occurs,
394 .I handle\->handle_bytes
395 is updated to indicate the required size for the handle.
396 .\"
397 .\"
398 .P
399 .BR open_by_handle_at ()
400 can fail with the following errors:
401 .TP
402 .B EBADF
403 .I mount_fd
404 is not an open file descriptor.
405 .TP
406 .B EBADF
407 .I path
408 is relative but
409 .I dirfd
410 is neither
411 .B AT_FDCWD
412 nor a valid file descriptor.
413 .TP
414 .B EFAULT
415 .I handle
416 points outside your accessible address space.
417 .TP
418 .B EINVAL
419 .I handle\->handle_bytes
420 is greater than
421 .B MAX_HANDLE_SZ
422 or is equal to zero.
423 .TP
424 .B ELOOP
425 .I handle
426 refers to a symbolic link, but
427 .B O_PATH
428 was not specified in
429 .IR flags .
430 .TP
431 .B EPERM
432 The caller does not have the
433 .B CAP_DAC_READ_SEARCH
434 capability.
435 .TP
436 .B ESTALE
437 The specified
438 .I handle
439 is not valid for opening a file.
440 This error will occur if, for example, the file has been deleted.
441 This error can also occur if the
442 .I handle
443 was acquired using the
444 .B AT_HANDLE_FID
445 flag and the filesystem does not support
446 .BR open_by_handle_at ().
447 This error can also occur if the
448 .I handle
449 was acquired using the
450 .B AT_HANDLE_CONNECTABLE
451 flag and the file was moved to a different parent.
452 .SH VERSIONS
453 FreeBSD has a broadly similar pair of system calls in the form of
454 .BR getfh ()
455 and
456 .BR fhopen ().
457 .SH STANDARDS
458 Linux.
459 .SH HISTORY
460 Linux 2.6.39,
461 glibc 2.14.
462 .SH NOTES
463 A file handle can be generated in one process using
464 .BR name_to_handle_at ()
465 and later used in a different process that calls
466 .BR open_by_handle_at ().
467 .P
468 Some filesystem don't support the translation of pathnames to
469 file handles, for example,
470 .IR /proc ,
471 .IR /sys ,
472 and various network filesystems.
473 Some filesystems support the translation of pathnames to
474 file handles, but do not support using those file handles in
475 .BR open_by_handle_at ().
476 .P
477 A file handle may become invalid ("stale") if a file is deleted,
478 or for other filesystem-specific reasons.
479 Invalid handles are notified by an
480 .B ESTALE
481 error from
482 .BR open_by_handle_at ().
483 .P
484 These system calls are designed for use by user-space file servers.
485 For example, a user-space NFS server might generate a file handle
486 and pass it to an NFS client.
487 Later, when the client wants to open the file,
488 it could pass the handle back to the server.
489 .\" https://lwn.net/Articles/375888/
490 .\" "Open by handle" - Jonathan Corbet, 2010-02-23
491 This sort of functionality allows a user-space file server to operate in
492 a stateless fashion with respect to the files it serves.
493 .P
494 If
495 .I path
496 refers to a symbolic link and
497 .I flags
498 does not specify
499 .BR AT_SYMLINK_FOLLOW ,
500 then
501 .BR name_to_handle_at ()
502 returns a handle for the link (rather than the file to which it refers).
503 .\" commit bcda76524cd1fa32af748536f27f674a13e56700
504 The process receiving the handle can later perform operations
505 on the symbolic link by converting the handle to a file descriptor using
506 .BR open_by_handle_at ()
507 with the
508 .B O_PATH
509 flag, and then passing the file descriptor as the
510 .I dirfd
511 argument in system calls such as
512 .BR readlinkat (2)
513 and
514 .BR fchownat (2).
515 .SS Obtaining a persistent filesystem ID
516 The mount IDs in
517 .I /proc/self/mountinfo
518 can be reused as filesystems are unmounted and mounted.
519 Therefore, the mount ID returned by
520 .BR name_to_handle_at ()
521 (in
522 .IR *mount_id )
523 should not be treated as a persistent identifier
524 for the corresponding mounted filesystem.
525 However, an application can use the information in the
526 .I mountinfo
527 record that corresponds to the mount ID
528 to derive a persistent identifier.
529 .P
530 For example, one can use the device name in the fifth field of the
531 .I mountinfo
532 record to search for the corresponding device UUID via the symbolic links in
533 .IR /dev/disks/by\-uuid .
534 (A more comfortable way of obtaining the UUID is to use the
535 .\" e.g., http://stackoverflow.com/questions/6748429/using-libblkid-to-find-uuid-of-a-partition
536 .BR libblkid (3)
537 library.)
538 That process can then be reversed,
539 using the UUID to look up the device name,
540 and then obtaining the corresponding mount point,
541 in order to produce the
542 .I mount_fd
543 argument used by
544 .BR open_by_handle_at ().
545 .SH EXAMPLES
546 The two programs below demonstrate the use of
547 .BR name_to_handle_at ()
548 and
549 .BR open_by_handle_at ().
550 The first program
551 .RI ( t_name_to_handle_at.c )
552 uses
553 .BR name_to_handle_at ()
554 to obtain the file handle and mount ID
555 for the file specified in its command-line argument;
556 the handle and mount ID are written to standard output.
557 .P
558 The second program
559 .RI ( t_open_by_handle_at.c )
560 reads a mount ID and file handle from standard input.
561 The program then employs
562 .BR open_by_handle_at ()
563 to open the file using that handle.
564 If an optional command-line argument is supplied, then the
565 .I mount_fd
566 argument for
567 .BR open_by_handle_at ()
568 is obtained by opening the directory named in that argument.
569 Otherwise,
570 .I mount_fd
571 is obtained by scanning
572 .I /proc/self/mountinfo
573 to find a record whose mount ID matches the mount ID
574 read from standard input,
575 and the mount directory specified in that record is opened.
576 (These programs do not deal with the fact that mount IDs are not persistent.)
577 .P
578 The following shell session demonstrates the use of these two programs:
579 .P
580 .in +4n
581 .EX
582 .RB $ " echo \[aq]Can you please think about it?\[aq] > cecilia.txt" ;
583 .RB $ " ./t_name_to_handle_at cecilia.txt > fh" ;
584 .RB $ " ./t_open_by_handle_at < fh" ;
585 open_by_handle_at: Operation not permitted
586 .RB $ " sudo ./t_open_by_handle_at < fh" "; # Need CAP_SYS_ADMIN"
587 Read 31 bytes
588 .RB $ " rm cecilia.txt" ;
589 .EE
590 .in
591 .P
592 Now we delete and (quickly) re-create the file so that
593 it has the same content and (by chance) the same inode.
594 Nevertheless,
595 .BR open_by_handle_at ()
596 .\" Christoph Hellwig: That's why the file handles contain a generation
597 .\" counter that gets incremented in this case.
598 recognizes that the original file referred to by the file handle
599 no longer exists.
600 .P
601 .in +4n
602 .EX
603 .RB $ " stat \-\-printf=\[dq]%i\[rs]n\[dq] cecilia.txt" "; # Display inode number"
604 4072121
605 .RB $ " rm cecilia.txt" ;
606 .RB $ " echo \[aq]Can you please think about it?\[aq] > cecilia.txt" ;
607 .RB $ " stat \-\-printf=\[dq]%i\[rs]n\[dq] cecilia.txt" "; # Check inode number"
608 4072121
609 .RB $ " sudo ./t_open_by_handle_at < fh" ;
610 open_by_handle_at: Stale NFS file handle
611 .EE
612 .in
613 .SS Program source: t_name_to_handle_at.c
614 \&
615 .\" SRC BEGIN (t_name_to_handle_at.c)
616 .EX
617 #define _GNU_SOURCE
618 #include <err.h>
619 #include <errno.h>
620 #include <fcntl.h>
621 #include <stdio.h>
622 #include <stdlib.h>
623 \&
624 int
625 main(int argc, char *argv[])
626 {
627 int mount_id, fhsize, flags, dirfd;
628 char *path;
629 struct file_handle *fhp;
630 \&
631 if (argc != 2) {
632 fprintf(stderr, "Usage: %s path\[rs]n", argv[0]);
633 exit(EXIT_FAILURE);
634 }
635 \&
636 path = argv[1];
637 \&
638 /* Allocate file_handle structure. */
639 \&
640 fhsize = sizeof(*fhp);
641 fhp = malloc(fhsize);
642 if (fhp == NULL)
643 err(EXIT_FAILURE, "malloc");
644 \&
645 /* Make an initial call to name_to_handle_at() to discover
646 the size required for file handle. */
647 \&
648 dirfd = AT_FDCWD; /* For name_to_handle_at() calls */
649 flags = 0; /* For name_to_handle_at() calls */
650 fhp\->handle_bytes = 0;
651 if (name_to_handle_at(dirfd, path, fhp, &mount_id, flags) != \-1
652 || errno != EOVERFLOW)
653 {
654 fprintf(stderr, "Unexpected result from name_to_handle_at()\[rs]n");
655 exit(EXIT_FAILURE);
656 }
657 \&
658 /* Reallocate file_handle structure with correct size. */
659 \&
660 fhsize = sizeof(*fhp) + fhp\->handle_bytes;
661 fhp = realloc(fhp, fhsize); /* Copies fhp\->handle_bytes */
662 if (fhp == NULL)
663 err(EXIT_FAILURE, "realloc");
664 \&
665 /* Get file handle from pathname supplied on command line. */
666 \&
667 if (name_to_handle_at(dirfd, path, fhp, &mount_id, flags) == \-1)
668 err(EXIT_FAILURE, "name_to_handle_at");
669 \&
670 /* Write mount ID, file handle size, and file handle to stdout,
671 for later reuse by t_open_by_handle_at.c. */
672 \&
673 printf("%d\[rs]n", mount_id);
674 printf("%u %d ", fhp\->handle_bytes, fhp\->handle_type);
675 for (size_t j = 0; j < fhp\->handle_bytes; j++)
676 printf(" %02x", fhp\->f_handle[j]);
677 printf("\[rs]n");
678 \&
679 exit(EXIT_SUCCESS);
680 }
681 .EE
682 .\" SRC END
683 .SS Program source: t_open_by_handle_at.c
684 \&
685 .\" SRC BEGIN (t_open_by_handle_at.c)
686 .EX
687 #define _GNU_SOURCE
688 #include <err.h>
689 #include <fcntl.h>
690 #include <limits.h>
691 #include <stdio.h>
692 #include <stdlib.h>
693 #include <string.h>
694 #include <sys/types.h>
695 #include <unistd.h>
696 \&
697 #define streq(...) (strcmp(__VA_ARGS__) == 0)
698 \&
699 /* Scan /proc/self/mountinfo to find the line whose mount ID matches
700 \[aq]mount_id\[aq]. (An easier way to do this is to install and use the
701 \[aq]libmount\[aq] library provided by the \[aq]util\-linux\[aq] project.)
702 Open the corresponding mount path and return the resulting file
703 descriptor. */
704 \&
705 static int
706 open_mount_path_by_id(int mount_id)
707 {
708 int mi_mount_id, found;
709 char mount_path[PATH_MAX];
710 char *linep;
711 FILE *fp;
712 size_t lsize;
713 ssize_t nread;
714 \&
715 fp = fopen("/proc/self/mountinfo", "r");
716 if (fp == NULL)
717 err(EXIT_FAILURE, "fopen");
718 \&
719 found = 0;
720 linep = NULL;
721 while (!found) {
722 nread = getline(&linep, &lsize, fp);
723 if (nread == \-1)
724 break;
725 \&
726 nread = sscanf(linep, "%d %*d %*s %*s %s",
727 &mi_mount_id, mount_path);
728 if (nread != 2) {
729 fprintf(stderr, "Bad sscanf()\[rs]n");
730 exit(EXIT_FAILURE);
731 }
732 \&
733 if (mi_mount_id == mount_id)
734 found = 1;
735 }
736 free(linep);
737 \&
738 fclose(fp);
739 \&
740 if (!found) {
741 fprintf(stderr, "Could not find mount point\[rs]n");
742 exit(EXIT_FAILURE);
743 }
744 \&
745 return open(mount_path, O_RDONLY);
746 }
747 \&
748 int
749 main(int argc, char *argv[])
750 {
751 int mount_id, fd, mount_fd, handle_bytes;
752 char buf[1000];
753 #define LINE_SIZE 100
754 char line1[LINE_SIZE], line2[LINE_SIZE];
755 char *nextp;
756 ssize_t nread;
757 struct file_handle *fhp;
758 \&
759 if ((argc > 1 && streq(argv[1], "\-\-help")) || argc > 2) {
760 fprintf(stderr, "Usage: %s [mount\-path]\[rs]n", argv[0]);
761 exit(EXIT_FAILURE);
762 }
763 \&
764 /* Standard input contains mount ID and file handle information:
765 \&
766 Line 1: <mount_id>
767 Line 2: <handle_bytes> <handle_type> <bytes of handle in hex>
768 */
769 \&
770 if (fgets(line1, sizeof(line1), stdin) == NULL ||
771 fgets(line2, sizeof(line2), stdin) == NULL)
772 {
773 fprintf(stderr, "Missing mount_id / file handle\[rs]n");
774 exit(EXIT_FAILURE);
775 }
776 \&
777 mount_id = atoi(line1);
778 \&
779 handle_bytes = strtoul(line2, &nextp, 0);
780 \&
781 /* Given handle_bytes, we can now allocate file_handle structure. */
782 \&
783 fhp = malloc(sizeof(*fhp) + handle_bytes);
784 if (fhp == NULL)
785 err(EXIT_FAILURE, "malloc");
786 \&
787 fhp\->handle_bytes = handle_bytes;
788 \&
789 fhp\->handle_type = strtoul(nextp, &nextp, 0);
790 \&
791 for (size_t j = 0; j < fhp\->handle_bytes; j++)
792 fhp\->f_handle[j] = strtoul(nextp, &nextp, 16);
793 \&
794 /* Obtain file descriptor for mount point, either by opening
795 the pathname specified on the command line, or by scanning
796 /proc/self/mounts to find a mount that matches the \[aq]mount_id\[aq]
797 that we received from stdin. */
798 \&
799 if (argc > 1)
800 mount_fd = open(argv[1], O_RDONLY);
801 else
802 mount_fd = open_mount_path_by_id(mount_id);
803 \&
804 if (mount_fd == \-1)
805 err(EXIT_FAILURE, "opening mount fd");
806 \&
807 /* Open file using handle and mount point. */
808 \&
809 fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);
810 if (fd == \-1)
811 err(EXIT_FAILURE, "open_by_handle_at");
812 \&
813 /* Try reading a few bytes from the file. */
814 \&
815 nread = read(fd, buf, sizeof(buf));
816 if (nread == \-1)
817 err(EXIT_FAILURE, "read");
818 \&
819 printf("Read %zd bytes\[rs]n", nread);
820 \&
821 exit(EXIT_SUCCESS);
822 }
823 .EE
824 .\" SRC END
825 .SH SEE ALSO
826 .BR open (2),
827 .BR libblkid (3),
828 .BR blkid (8),
829 .BR findfs (8),
830 .BR mount (8)
831 .P
832 The
833 .I libblkid
834 and
835 .I libmount
836 documentation in the latest
837 .I util\-linux
838 release at
839 .UR https:\://www.kernel.org/pub/linux/utils/util\-linux/
840 .UE