Merging upstream version 6.8.

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

1 files changed, 421 insertions, 0 deletions

diff --git a/man/man2/kcmp.2 b/man/man2/kcmp.2
new file mode 100644
index 0000000..0add272
--- /dev/null
+++ b/man/man2/kcmp.2
@@ -0,0 +1,421 @@
+.\" Copyright (C) 2012, Cyrill Gorcunov <gorcunov@openvz.org>
+.\" and Copyright (C) 2012, 2016, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d
+.\"
+.TH kcmp 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+kcmp \- compare two processes to determine if they share a kernel resource
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/kcmp.h>" "       /* Definition of " KCMP_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type ,
+.BI "            unsigned long " idx1 ", unsigned long "  idx2 );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR kcmp (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+The
+.BR kcmp ()
+system call can be used to check whether the two processes identified by
+.I pid1
+and
+.I pid2
+share a kernel resource such as virtual memory, file descriptors,
+and so on.
+.P
+Permission to employ
+.BR kcmp ()
+is governed by ptrace access mode
+.B PTRACE_MODE_READ_REALCREDS
+checks against both
+.I pid1
+and
+.IR pid2 ;
+see
+.BR ptrace (2).
+.P
+The
+.I type
+argument specifies which resource is to be compared in the two processes.
+It has one of the following values:
+.TP
+.B KCMP_FILE
+Check whether a file descriptor
+.I idx1
+in the process
+.I pid1
+refers to the same open file description (see
+.BR open (2))
+as file descriptor
+.I idx2
+in the process
+.IR pid2 .
+The existence of two file descriptors that refer to the same
+open file description can occur as a result of
+.BR dup (2)
+(and similar)
+.BR fork (2),
+or passing file descriptors via a domain socket (see
+.BR unix (7)).
+.TP
+.B KCMP_FILES
+Check whether the processes share the same set of open file descriptors.
+The arguments
+.I idx1
+and
+.I idx2
+are ignored.
+See the discussion of the
+.B CLONE_FILES
+flag in
+.BR clone (2).
+.TP
+.B KCMP_FS
+Check whether the processes share the same filesystem information
+(i.e., file mode creation mask, working directory, and filesystem root).
+The arguments
+.I idx1
+and
+.I idx2
+are ignored.
+See the discussion of the
+.B CLONE_FS
+flag in
+.BR clone (2).
+.TP
+.B KCMP_IO
+Check whether the processes share I/O context.
+The arguments
+.I idx1
+and
+.I idx2
+are ignored.
+See the discussion of the
+.B CLONE_IO
+flag in
+.BR clone (2).
+.TP
+.B KCMP_SIGHAND
+Check whether the processes share the same table of signal dispositions.
+The arguments
+.I idx1
+and
+.I idx2
+are ignored.
+See the discussion of the
+.B CLONE_SIGHAND
+flag in
+.BR clone (2).
+.TP
+.B KCMP_SYSVSEM
+Check whether the processes share the same
+list of System\ V semaphore undo operations.
+The arguments
+.I idx1
+and
+.I idx2
+are ignored.
+See the discussion of the
+.B CLONE_SYSVSEM
+flag in
+.BR clone (2).
+.TP
+.B KCMP_VM
+Check whether the processes share the same address space.
+The arguments
+.I idx1
+and
+.I idx2
+are ignored.
+See the discussion of the
+.B CLONE_VM
+flag in
+.BR clone (2).
+.TP
+.BR KCMP_EPOLL_TFD " (since Linux 4.13)"
+.\" commit 0791e3644e5ef21646fe565b9061788d05ec71d4
+Check whether the file descriptor
+.I idx1
+of the process
+.I pid1
+is present in the
+.BR epoll (7)
+instance described by
+.I idx2
+of the process
+.IR pid2 .
+The argument
+.I idx2
+is a pointer to a structure where the target file is described.
+This structure has the form:
+.P
+.in +4n
+.EX
+struct kcmp_epoll_slot {
+    __u32 efd;
+    __u32 tfd;
+    __u64 toff;
+};
+.EE
+.in
+.P
+Within this structure,
+.I efd
+is an epoll file descriptor returned from
+.BR epoll_create (2),
+.I tfd
+is a target file descriptor number, and
+.I toff
+is a target file offset counted from zero.
+Several different targets may be registered with
+the same file descriptor number and setting a specific
+offset helps to investigate each of them.
+.P
+Note the
+.BR kcmp ()
+is not protected against false positives which may occur if
+the processes are currently running.
+One should stop the processes by sending
+.B SIGSTOP
+(see
+.BR signal (7))
+prior to inspection with this system call to obtain meaningful results.
+.SH RETURN VALUE
+The return value of a successful call to
+.BR kcmp ()
+is simply the result of arithmetic comparison
+of kernel pointers (when the kernel compares resources, it uses their
+memory addresses).
+.P
+The easiest way to explain is to consider an example.
+Suppose that
+.I v1
+and
+.I v2
+are the addresses of appropriate resources, then the return value
+is one of the following:
+.RS
+.TP
+.B 0
+.I v1
+is equal to
+.IR v2 ;
+in other words, the two processes share the resource.
+.TP
+.B 1
+.I v1
+is less than
+.IR v2 .
+.TP
+.B 2
+.I v1
+is greater than
+.IR v2 .
+.TP
+.B 3
+.I v1
+is not equal to
+.IR v2 ,
+but ordering information is unavailable.
+.RE
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.P
+.BR kcmp ()
+was designed to return values suitable for sorting.
+This is particularly handy if one needs to compare
+a large number of file descriptors.
+.SH ERRORS
+.TP
+.B EBADF
+.I type
+is
+.B KCMP_FILE
+and
+.I fd1
+or
+.I fd2
+is not an open file descriptor.
+.TP
+.B EFAULT
+The epoll slot addressed by
+.I idx2
+is outside of the user's address space.
+.TP
+.B EINVAL
+.I type
+is invalid.
+.TP
+.B ENOENT
+The target file is not present in
+.BR epoll (7)
+instance.
+.TP
+.B EPERM
+Insufficient permission to inspect process resources.
+The
+.B CAP_SYS_PTRACE
+capability is required to inspect processes that you do not own.
+Other ptrace limitations may also apply, such as
+.BR CONFIG_SECURITY_YAMA ,
+which, when
+.I /proc/sys/kernel/yama/ptrace_scope
+is 2, limits
+.BR kcmp ()
+to child processes;
+see
+.BR ptrace (2).
+.TP
+.B ESRCH
+Process
+.I pid1
+or
+.I pid2
+does not exist.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 3.5.
+.P
+Before Linux 5.12,
+this system call is available only if the kernel is configured with
+.BR CONFIG_CHECKPOINT_RESTORE ,
+since the original purpose of the system call was for the
+checkpoint/restore in user space (CRIU) feature.
+(The alternative to this system call would have been to expose suitable
+process information via the
+.BR proc (5)
+filesystem; this was deemed to be unsuitable for security reasons.)
+Since Linux 5.12,
+this system call is also available if the kernel is configured with
+.BR CONFIG_KCMP .
+.SH NOTES
+See
+.BR clone (2)
+for some background information on the shared resources
+referred to on this page.
+.SH EXAMPLES
+The program below uses
+.BR kcmp ()
+to test whether pairs of file descriptors refer to
+the same open file description.
+The program tests different cases for the file descriptor pairs,
+as described in the program output.
+An example run of the program is as follows:
+.P
+.in +4n
+.EX
+$ \fB./a.out\fP
+Parent PID is 1144
+Parent opened file on FD 3
+\&
+PID of child of fork() is 1145
+	Compare duplicate FDs from different processes:
+		kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same
+Child opened file on FD 4
+	Compare FDs from distinct open()s in same process:
+		kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different
+Child duplicated FD 3 to create FD 5
+	Compare duplicated FDs in same process:
+		kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (kcmp.c)
+.EX
+#define _GNU_SOURCE
+#include <err.h>
+#include <fcntl.h>
+#include <linux/kcmp.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/syscall.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+#include <unistd.h>
+\&
+static int
+kcmp(pid_t pid1, pid_t pid2, int type,
+     unsigned long idx1, unsigned long idx2)
+{
+    return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2);
+}
+\&
+static void
+test_kcmp(char *msg, pid_t pid1, pid_t pid2, int fd_a, int fd_b)
+{
+    printf("\et%s\en", msg);
+    printf("\et\etkcmp(%jd, %jd, KCMP_FILE, %d, %d) ==> %s\en",
+           (intmax_t) pid1, (intmax_t) pid2, fd_a, fd_b,
+           (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ?
+                        "same" : "different");
+}
+\&
+int
+main(void)
+{
+    int                fd1, fd2, fd3;
+    static const char  pathname[] = "/tmp/kcmp.test";
+\&
+    fd1 = open(pathname, O_CREAT | O_RDWR, 0600);
+    if (fd1 == \-1)
+        err(EXIT_FAILURE, "open");
+\&
+    printf("Parent PID is %jd\en", (intmax_t) getpid());
+    printf("Parent opened file on FD %d\en\en", fd1);
+\&
+    switch (fork()) {
+    case \-1:
+        err(EXIT_FAILURE, "fork");
+\&
+    case 0:
+        printf("PID of child of fork() is %jd\en", (intmax_t) getpid());
+\&
+        test_kcmp("Compare duplicate FDs from different processes:",
+                  getpid(), getppid(), fd1, fd1);
+\&
+        fd2 = open(pathname, O_CREAT | O_RDWR, 0600);
+        if (fd2 == \-1)
+            err(EXIT_FAILURE, "open");
+        printf("Child opened file on FD %d\en", fd2);
+\&
+        test_kcmp("Compare FDs from distinct open()s in same process:",
+                  getpid(), getpid(), fd1, fd2);
+\&
+        fd3 = dup(fd1);
+        if (fd3 == \-1)
+            err(EXIT_FAILURE, "dup");
+        printf("Child duplicated FD %d to create FD %d\en", fd1, fd3);
+\&
+        test_kcmp("Compare duplicated FDs in same process:",
+                  getpid(), getpid(), fd1, fd3);
+        break;
+\&
+    default:
+        wait(NULL);
+    }
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR clone (2),
+.BR unshare (2)