Merging upstream version 4.23.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 68 insertions, 31 deletions

diff --git a/upstream/opensuse-tumbleweed/man2/open_by_handle_at.2 b/upstream/opensuse-tumbleweed/man2/open_by_handle_at.2
index b5e3d75f..eb2ffccf 100644
--- a/upstream/opensuse-tumbleweed/man2/open_by_handle_at.2
+++ b/upstream/opensuse-tumbleweed/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 2024-05-02 "Linux man-pages (unreleased)"
 .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
@@ -605,6 +641,7 @@ main(int argc, char *argv[])
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include <sys/types.h>
 #include <unistd.h>
 \&
 /* Scan /proc/self/mountinfo to find the line whose mount ID matches
@@ -739,7 +776,7 @@ main(int argc, char *argv[])
 .BR blkid (8),
 .BR findfs (8),
 .BR mount (8)
-.PP
+.P
 The
 .I libblkid
 and