diff options
Diffstat (limited to 'man2/kcmp.2')
| -rw-r--r-- | man2/kcmp.2 | 420 |
1 files changed, 0 insertions, 420 deletions
diff --git a/man2/kcmp.2 b/man2/kcmp.2 deleted file mode 100644 index 0ea604eac..000000000 --- a/man2/kcmp.2 +++ /dev/null @@ -1,420 +0,0 @@ -.\" 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 (date) "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/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) |