diff options
Diffstat (limited to 'man2/open_by_handle_at.2')
| -rw-r--r-- | man2/open_by_handle_at.2 | 98 |
1 files changed, 67 insertions, 31 deletions
diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index b5e3d75..26bb9c2 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH open_by_handle_at 2 2023-05-03 "Linux man-pages 6.05.01" +.TH open_by_handle_at 2 2023-10-31 "Linux man-pages 6.7" .SH NAME name_to_handle_at, open_by_handle_at \- obtain handle for a pathname and open file via a handle @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <fcntl.h> -.PP +.P .BI "int name_to_handle_at(int " dirfd ", const char *" pathname , .BI " struct file_handle *" handle , .BI " int *" mount_id ", int " flags ); @@ -48,7 +48,7 @@ arguments. The file handle is returned via the argument .IR handle , which is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct file_handle { @@ -59,7 +59,7 @@ struct file_handle { }; .EE .in -.PP +.P It is the caller's responsibility to allocate the structure with a size large enough to hold the handle returned in .IR f_handle . @@ -78,7 +78,7 @@ Upon successful return, the .I handle_bytes field is updated to contain the number of bytes actually written to .IR f_handle . -.PP +.P The caller can discover the required size for the .I file_handle structure by making a call in which @@ -100,7 +100,7 @@ This case can be detected when the error is returned without .I handle_bytes being increased. -.PP +.P Other than the use of the .I handle_bytes field, the caller should treat the @@ -109,17 +109,44 @@ structure as an opaque data type: the .I handle_type and .I f_handle -fields are needed only by a subsequent call to +fields can be used in a subsequent call to .BR open_by_handle_at (). -.PP +The caller can also use the opaque +.I file_handle +to compare the identity of filesystem objects +that were queried at different times and possibly +at different paths. +The +.BR fanotify (7) +subsystem can report events +with an information record containing a +.I file_handle +to identify the filesystem object. +.P The .I flags argument is a bit mask constructed by ORing together zero or more of -.B AT_EMPTY_PATH +.BR AT_HANDLE_FID , +.BR AT_EMPTY_PATH , and .BR AT_SYMLINK_FOLLOW , described below. -.PP +.P +When +.I flags +contain the +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +flag, the caller indicates that the returned +.I file_handle +is needed to identify the filesystem object, +and not for opening the file later, +so it should be expected that a subsequent call to +.BR open_by_handle_at () +with the returned +.I file_handle +may fail. +.P Together, the .I pathname and @@ -172,7 +199,7 @@ or .BR AT_FDCWD , meaning the current working directory, and a handle is returned for the file to which it refers. -.PP +.P The .I mount_id argument returns an identifier for the filesystem @@ -188,7 +215,7 @@ that file descriptor can be used in a subsequent call to is returned both for a successful call and for a call that results in the error .BR EOVERFLOW . -.PP +.P By default, .BR name_to_handle_at () does not dereference @@ -201,7 +228,7 @@ is specified in .I pathname is dereferenced if it is a symbolic link (so that the call returns a handle for the file referred to by the link). -.PP +.P .BR name_to_handle_at () does not trigger a mount when the final component of the pathname is an automount point. @@ -225,7 +252,7 @@ system call opens the file referred to by .IR handle , a file handle returned by a previous call to .BR name_to_handle_at (). -.PP +.P The .I mount_fd argument is a file descriptor for any object (file, directory, etc.) @@ -235,7 +262,7 @@ should be interpreted. The special value .B AT_FDCWD can be specified, meaning the current working directory of the caller. -.PP +.P The .I flags argument @@ -248,7 +275,7 @@ refers to a symbolic link, the caller must specify the flag, and the symbolic link is not dereferenced; the .B O_NOFOLLOW flag, if specified, is ignored. -.PP +.P The caller must have the .B CAP_DAC_READ_SEARCH capability to invoke @@ -260,7 +287,7 @@ returns 0, and .BR open_by_handle_at () returns a file descriptor (a nonnegative integer). -.PP +.P In the event of an error, both system calls return \-1 and set .I errno to indicate the error. @@ -271,7 +298,7 @@ and can fail for the same errors as .BR openat (2). In addition, they can fail with the errors noted below. -.PP +.P .BR name_to_handle_at () can fail with the following errors: .TP @@ -322,7 +349,7 @@ When this error occurs, is updated to indicate the required size for the handle. .\" .\" -.PP +.P .BR open_by_handle_at () can fail with the following errors: .TP @@ -363,8 +390,14 @@ capability. .B ESTALE The specified .I handle -is not valid. +is not valid for opening a file. This error will occur if, for example, the file has been deleted. +This error can also occur if the +.I handle +was acquired using the +.B AT_HANDLE_FID +flag and the filesystem does not support +.BR open_by_handle_at (). .SH VERSIONS FreeBSD has a broadly similar pair of system calls in the form of .BR getfh () @@ -380,20 +413,23 @@ A file handle can be generated in one process using .BR name_to_handle_at () and later used in a different process that calls .BR open_by_handle_at (). -.PP +.P Some filesystem don't support the translation of pathnames to file handles, for example, .IR /proc , .IR /sys , and various network filesystems. -.PP +Some filesystems support the translation of pathnames to +file handles, but do not support using those file handles in +.BR open_by_handle_at (). +.P A file handle may become invalid ("stale") if a file is deleted, or for other filesystem-specific reasons. Invalid handles are notified by an .B ESTALE error from .BR open_by_handle_at (). -.PP +.P These system calls are designed for use by user-space file servers. For example, a user-space NFS server might generate a file handle and pass it to an NFS client. @@ -403,7 +439,7 @@ it could pass the handle back to the server. .\" "Open by handle" - Jonathan Corbet, 2010-02-23 This sort of functionality allows a user-space file server to operate in a stateless fashion with respect to the files it serves. -.PP +.P If .I pathname refers to a symbolic link and @@ -439,7 +475,7 @@ However, an application can use the information in the .I mountinfo record that corresponds to the mount ID to derive a persistent identifier. -.PP +.P For example, one can use the device name in the fifth field of the .I mountinfo record to search for the corresponding device UUID via the symbolic links in @@ -467,7 +503,7 @@ uses to obtain the file handle and mount ID for the file specified in its command-line argument; the handle and mount ID are written to standard output. -.PP +.P The second program .RI ( t_open_by_handle_at.c ) reads a mount ID and file handle from standard input. @@ -487,9 +523,9 @@ to find a record whose mount ID matches the mount ID read from standard input, and the mount directory specified in that record is opened. (These programs do not deal with the fact that mount IDs are not persistent.) -.PP +.P The following shell session demonstrates the use of these two programs: -.PP +.P .in +4n .EX $ \fBecho \[aq]Can you please think about it?\[aq] > cecilia.txt\fP @@ -501,7 +537,7 @@ Read 31 bytes $ \fBrm cecilia.txt\fP .EE .in -.PP +.P Now we delete and (quickly) re-create the file so that it has the same content and (by chance) the same inode. Nevertheless, @@ -510,7 +546,7 @@ Nevertheless, .\" counter that gets incremented in this case. recognizes that the original file referred to by the file handle no longer exists. -.PP +.P .in +4n .EX $ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Display inode number @@ -739,7 +775,7 @@ main(int argc, char *argv[]) .BR blkid (8), .BR findfs (8), .BR mount (8) -.PP +.P The .I libblkid and |