| 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 |