1kcmp(2)                       System Calls Manual                      kcmp(2)
2
3
4

NAME

6       kcmp  -  compare  two processes to determine if they share a kernel re‐
7       source
8

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <linux/kcmp.h>       /* Definition of KCMP_* constants */
14       #include <sys/syscall.h>      /* Definition of SYS_* constants */
15       #include <unistd.h>
16
17       int syscall(SYS_kcmp, pid_t pid1, pid_t pid2, int type,
18                   unsigned long idx1, unsigned long idx2);
19
20       Note: glibc provides no wrapper for kcmp(), necessitating  the  use  of
21       syscall(2).
22

DESCRIPTION

24       The  kcmp()  system call can be used to check whether the two processes
25       identified by pid1 and pid2 share a kernel  resource  such  as  virtual
26       memory, file descriptors, and so on.
27
28       Permission   to  employ  kcmp()  is  governed  by  ptrace  access  mode
29       PTRACE_MODE_READ_REALCREDS checks  against  both  pid1  and  pid2;  see
30       ptrace(2).
31
32       The type argument specifies which resource is to be compared in the two
33       processes.  It has one of the following values:
34
35       KCMP_FILE
36              Check whether a file descriptor idx1 in the process pid1  refers
37              to the same open file description (see open(2)) as file descrip‐
38              tor idx2 in the process pid2.  The existence  of  two  file  de‐
39              scriptors that refer to the same open file description can occur
40              as a result of dup(2) (and similar) fork(2), or passing file de‐
41              scriptors via a domain socket (see unix(7)).
42
43       KCMP_FILES
44              Check  whether the processes share the same set of open file de‐
45              scriptors.  The arguments idx1 and idx2 are  ignored.   See  the
46              discussion of the CLONE_FILES flag in clone(2).
47
48       KCMP_FS
49              Check  whether  the processes share the same filesystem informa‐
50              tion (i.e., file mode  creation  mask,  working  directory,  and
51              filesystem root).  The arguments idx1 and idx2 are ignored.  See
52              the discussion of the CLONE_FS flag in clone(2).
53
54       KCMP_IO
55              Check whether the processes share I/O  context.   The  arguments
56              idx1  and  idx2 are ignored.  See the discussion of the CLONE_IO
57              flag in clone(2).
58
59       KCMP_SIGHAND
60              Check whether the processes share the same table of signal  dis‐
61              positions.   The  arguments  idx1 and idx2 are ignored.  See the
62              discussion of the CLONE_SIGHAND flag in clone(2).
63
64       KCMP_SYSVSEM
65              Check whether the processes share the same list of System V sem‐
66              aphore  undo  operations.   The  arguments idx1 and idx2 are ig‐
67              nored.   See  the  discussion  of  the  CLONE_SYSVSEM  flag   in
68              clone(2).
69
70       KCMP_VM
71              Check  whether  the processes share the same address space.  The
72              arguments idx1 and idx2 are ignored.  See the discussion of  the
73              CLONE_VM flag in clone(2).
74
75       KCMP_EPOLL_TFD (since Linux 4.13)
76              Check  whether  the  file descriptor idx1 of the process pid1 is
77              present in the  epoll(7)  instance  described  by  idx2  of  the
78              process  pid2.   The  argument  idx2 is a pointer to a structure
79              where the target file is  described.   This  structure  has  the
80              form:
81
82           struct kcmp_epoll_slot {
83               __u32 efd;
84               __u32 tfd;
85               __u64 toff;
86           };
87
88       Within  this  structure,  efd is an epoll file descriptor returned from
89       epoll_create(2), tfd is a target file descriptor number, and toff is  a
90       target file offset counted from zero.  Several different targets may be
91       registered with the same file descriptor number and setting a  specific
92       offset helps to investigate each of them.
93
94       Note  the kcmp() is not protected against false positives which may oc‐
95       cur if the processes are currently running.  One should stop  the  pro‐
96       cesses by sending SIGSTOP (see signal(7)) prior to inspection with this
97       system call to obtain meaningful results.
98

RETURN VALUE

100       The return value of a successful call to kcmp() is simply the result of
101       arithmetic  comparison of kernel pointers (when the kernel compares re‐
102       sources, it uses their memory addresses).
103
104       The easiest way to explain is to consider an example.  Suppose that  v1
105       and  v2  are  the  addresses  of appropriate resources, then the return
106       value is one of the following:
107
108              0      v1 is equal to v2; in  other  words,  the  two  processes
109                     share the resource.
110
111              1      v1 is less than v2.
112
113              2      v1 is greater than v2.
114
115              3      v1  is  not  equal to v2, but ordering information is un‐
116                     available.
117
118       On error, -1 is returned, and errno is set to indicate the error.
119
120       kcmp() was designed to return values suitable  for  sorting.   This  is
121       particularly  handy  if one needs to compare a large number of file de‐
122       scriptors.
123

ERRORS

125       EBADF  type is KCMP_FILE and fd1 or fd2 is not an open file descriptor.
126
127       EFAULT The epoll slot addressed by idx2 is outside of  the  user's  ad‐
128              dress space.
129
130       EINVAL type is invalid.
131
132       ENOENT The target file is not present in epoll(7) instance.
133
134       EPERM  Insufficient  permission  to  inspect  process  resources.   The
135              CAP_SYS_PTRACE capability is required to inspect processes  that
136              you  do  not own.  Other ptrace limitations may also apply, such
137              as    CONFIG_SECURITY_YAMA,    which,    when     /proc/sys/ker‐
138              nel/yama/ptrace_scope  is  2,  limits kcmp() to child processes;
139              see ptrace(2).
140
141       ESRCH  Process pid1 or pid2 does not exist.
142

STANDARDS

144       Linux.
145

HISTORY

147       Linux 3.5.
148
149       Before Linux 5.12, this system call is available only if the kernel  is
150       configured  with  CONFIG_CHECKPOINT_RESTORE, since the original purpose
151       of the system call was for the checkpoint/restore in user space  (CRIU)
152       feature.   (The  alternative to this system call would have been to ex‐
153       pose suitable process information via the proc(5) filesystem; this  was
154       deemed  to be unsuitable for security reasons.)  Since Linux 5.12, this
155       system call is also available if the kernel  is  configured  with  CON‐
156       FIG_KCMP.
157

NOTES

159       See  clone(2)  for  some background information on the shared resources
160       referred to on this page.
161

EXAMPLES

163       The program below uses kcmp() to test whether pairs of file descriptors
164       refer  to  the same open file description.  The program tests different
165       cases for the file descriptor pairs, as described in the  program  out‐
166       put.  An example run of the program is as follows:
167
168           $ ./a.out
169           Parent PID is 1144
170           Parent opened file on FD 3
171
172           PID of child of fork() is 1145
173                Compare duplicate FDs from different processes:
174                     kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same
175           Child opened file on FD 4
176                Compare FDs from distinct open()s in same process:
177                     kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different
178           Child duplicated FD 3 to create FD 5
179                Compare duplicated FDs in same process:
180                     kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same
181
182   Program source
183
184       #define _GNU_SOURCE
185       #include <err.h>
186       #include <fcntl.h>
187       #include <linux/kcmp.h>
188       #include <stdint.h>
189       #include <stdio.h>
190       #include <stdlib.h>
191       #include <sys/syscall.h>
192       #include <sys/wait.h>
193       #include <unistd.h>
194
195       static int
196       kcmp(pid_t pid1, pid_t pid2, int type,
197            unsigned long idx1, unsigned long idx2)
198       {
199           return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2);
200       }
201
202       static void
203       test_kcmp(char *msg, pid_t pid1, pid_t pid2, int fd_a, int fd_b)
204       {
205           printf("\t%s\n", msg);
206           printf("\t\tkcmp(%jd, %jd, KCMP_FILE, %d, %d) ==> %s\n",
207                  (intmax_t) pid1, (intmax_t) pid2, fd_a, fd_b,
208                  (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ?
209                               "same" : "different");
210       }
211
212       int
213       main(void)
214       {
215           int                fd1, fd2, fd3;
216           static const char  pathname[] = "/tmp/kcmp.test";
217
218           fd1 = open(pathname, O_CREAT | O_RDWR, 0600);
219           if (fd1 == -1)
220               err(EXIT_FAILURE, "open");
221
222           printf("Parent PID is %jd\n", (intmax_t) getpid());
223           printf("Parent opened file on FD %d\n\n", fd1);
224
225           switch (fork()) {
226           case -1:
227               err(EXIT_FAILURE, "fork");
228
229           case 0:
230               printf("PID of child of fork() is %jd\n", (intmax_t) getpid());
231
232               test_kcmp("Compare duplicate FDs from different processes:",
233                         getpid(), getppid(), fd1, fd1);
234
235               fd2 = open(pathname, O_CREAT | O_RDWR, 0600);
236               if (fd2 == -1)
237                   err(EXIT_FAILURE, "open");
238               printf("Child opened file on FD %d\n", fd2);
239
240               test_kcmp("Compare FDs from distinct open()s in same process:",
241                         getpid(), getpid(), fd1, fd2);
242
243               fd3 = dup(fd1);
244               if (fd3 == -1)
245                   err(EXIT_FAILURE, "dup");
246               printf("Child duplicated FD %d to create FD %d\n", fd1, fd3);
247
248               test_kcmp("Compare duplicated FDs in same process:",
249                         getpid(), getpid(), fd1, fd3);
250               break;
251
252           default:
253               wait(NULL);
254           }
255
256           exit(EXIT_SUCCESS);
257       }
258

SEE ALSO

260       clone(2), unshare(2)
261
262
263
264Linux man-pages 6.05              2023-05-03                           kcmp(2)
Impressum