Debian Codegraph @

upstream/debian-unstable/man2/kcmp.2

raw
1 .\" Copyright 2012, Cyrill Gorcunov <[email protected]>
2 .\" Copyright 2012-2016, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d
8 .\"
9 .TH kcmp 2 2026-02-08 "Linux man-pages 6.18"
10 .SH NAME
11 kcmp \- compare two processes to determine if they share a kernel resource
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/kcmp.h>" " /* Definition of " KCMP_* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type ,
22 .BI " unsigned long " idx1 ", unsigned long " idx2 );
23 .fi
24 .P
25 .IR Note :
26 glibc provides no wrapper for
27 .BR kcmp (),
28 necessitating the use of
29 .BR syscall (2).
30 .SH DESCRIPTION
31 The
32 .BR kcmp ()
33 system call can be used to check whether the two processes identified by
34 .I pid1
35 and
36 .I pid2
37 share a kernel resource such as virtual memory, file descriptors,
38 and so on.
39 .P
40 Permission to employ
41 .BR kcmp ()
42 is governed by ptrace access mode
43 .B PTRACE_MODE_READ_REALCREDS
44 checks against both
45 .I pid1
46 and
47 .IR pid2 ;
48 see
49 .BR ptrace (2).
50 .P
51 The
52 .I type
53 argument specifies which resource is to be compared in the two processes.
54 It has one of the following values:
55 .TP
56 .B KCMP_FILE
57 Check whether a file descriptor
58 .I idx1
59 in the process
60 .I pid1
61 refers to the same open file description (see
62 .BR open (2))
63 as file descriptor
64 .I idx2
65 in the process
66 .IR pid2 .
67 The existence of two file descriptors that refer to the same
68 open file description can occur as a result of
69 .BR dup (2)
70 (and similar)
71 .BR fork (2),
72 or passing file descriptors via a domain socket (see
73 .BR unix (7)).
74 .TP
75 .B KCMP_FILES
76 Check whether the processes share the same set of open file descriptors.
77 The arguments
78 .I idx1
79 and
80 .I idx2
81 are ignored.
82 See the discussion of the
83 .B CLONE_FILES
84 flag in
85 .BR clone (2).
86 .TP
87 .B KCMP_FS
88 Check whether the processes share the same filesystem information
89 (i.e., file mode creation mask, working directory, and filesystem root).
90 The arguments
91 .I idx1
92 and
93 .I idx2
94 are ignored.
95 See the discussion of the
96 .B CLONE_FS
97 flag in
98 .BR clone (2).
99 .TP
100 .B KCMP_IO
101 Check whether the processes share I/O context.
102 The arguments
103 .I idx1
104 and
105 .I idx2
106 are ignored.
107 See the discussion of the
108 .B CLONE_IO
109 flag in
110 .BR clone (2).
111 .TP
112 .B KCMP_SIGHAND
113 Check whether the processes share the same table of signal dispositions.
114 The arguments
115 .I idx1
116 and
117 .I idx2
118 are ignored.
119 See the discussion of the
120 .B CLONE_SIGHAND
121 flag in
122 .BR clone (2).
123 .TP
124 .B KCMP_SYSVSEM
125 Check whether the processes share the same
126 list of System\ V semaphore undo operations.
127 The arguments
128 .I idx1
129 and
130 .I idx2
131 are ignored.
132 See the discussion of the
133 .B CLONE_SYSVSEM
134 flag in
135 .BR clone (2).
136 .TP
137 .B KCMP_VM
138 Check whether the processes share the same address space.
139 The arguments
140 .I idx1
141 and
142 .I idx2
143 are ignored.
144 See the discussion of the
145 .B CLONE_VM
146 flag in
147 .BR clone (2).
148 .TP
149 .BR KCMP_EPOLL_TFD " (since Linux 4.13)"
150 .\" commit 0791e3644e5ef21646fe565b9061788d05ec71d4
151 Check whether the file descriptor
152 .I idx1
153 of the process
154 .I pid1
155 is present in the
156 .BR epoll (7)
157 instance described by
158 .I idx2
159 of the process
160 .IR pid2 .
161 The argument
162 .I idx2
163 is a pointer to a structure where the target file is described.
164 This structure has the form:
165 .P
166 .in +4n
167 .EX
168 struct kcmp_epoll_slot {
169 __u32 efd;
170 __u32 tfd;
171 __u64 toff;
172 };
173 .EE
174 .in
175 .P
176 Within this structure,
177 .I efd
178 is an epoll file descriptor returned from
179 .BR epoll_create (2),
180 .I tfd
181 is a target file descriptor number, and
182 .I toff
183 is a target file offset counted from zero.
184 Several different targets may be registered with
185 the same file descriptor number and setting a specific
186 offset helps to investigate each of them.
187 .P
188 Note the
189 .BR kcmp ()
190 is not protected against false positives which may occur if
191 the processes are currently running.
192 One should stop the processes by sending
193 .B SIGSTOP
194 (see
195 .BR signal (7))
196 prior to inspection with this system call to obtain meaningful results.
197 .SH RETURN VALUE
198 The return value of a successful call to
199 .BR kcmp ()
200 is simply the result of arithmetic comparison
201 of kernel pointers (when the kernel compares resources, it uses their
202 memory addresses).
203 .P
204 The easiest way to explain is to consider an example.
205 Suppose that
206 .I v1
207 and
208 .I v2
209 are the addresses of appropriate resources, then the return value
210 is one of the following:
211 .RS
212 .TP
213 .B 0
214 .I v1
215 is equal to
216 .IR v2 ;
217 in other words, the two processes share the resource.
218 .TP
219 .B 1
220 .I v1
221 is less than
222 .IR v2 .
223 .TP
224 .B 2
225 .I v1
226 is greater than
227 .IR v2 .
228 .TP
229 .B 3
230 .I v1
231 is not equal to
232 .IR v2 ,
233 but ordering information is unavailable.
234 .RE
235 .P
236 On error, \-1 is returned, and
237 .I errno
238 is set to indicate the error.
239 .P
240 .BR kcmp ()
241 was designed to return values suitable for sorting.
242 This is particularly handy if one needs to compare
243 a large number of file descriptors.
244 .SH ERRORS
245 .TP
246 .B EBADF
247 .I type
248 is
249 .B KCMP_FILE
250 and
251 .I fd1
252 or
253 .I fd2
254 is not an open file descriptor.
255 .TP
256 .B EFAULT
257 The epoll slot addressed by
258 .I idx2
259 is outside of the user's address space.
260 .TP
261 .B EINVAL
262 .I type
263 is invalid.
264 .TP
265 .B ENOENT
266 The target file is not present in
267 .BR epoll (7)
268 instance.
269 .TP
270 .B EPERM
271 Insufficient permission to inspect process resources.
272 The
273 .B CAP_SYS_PTRACE
274 capability is required to inspect processes that you do not own.
275 Other ptrace limitations may also apply, such as
276 .BR CONFIG_SECURITY_YAMA ,
277 which, when
278 .I /proc/sys/kernel/yama/ptrace_scope
279 is 2, limits
280 .BR kcmp ()
281 to child processes;
282 see
283 .BR ptrace (2).
284 .TP
285 .B ESRCH
286 Process
287 .I pid1
288 or
289 .I pid2
290 does not exist.
291 .SH STANDARDS
292 Linux.
293 .SH HISTORY
294 Linux 3.5.
295 .P
296 Before Linux 5.12,
297 this system call is available only if the kernel is configured with
298 .BR CONFIG_CHECKPOINT_RESTORE ,
299 since the original purpose of the system call was for the
300 checkpoint/restore in user space (CRIU) feature.
301 (The alternative to this system call would have been to
302 expose suitable process information via the
303 .BR proc (5)
304 filesystem;
305 this was deemed to be unsuitable for security reasons.)
306 Since Linux 5.12,
307 this system call is also available if the kernel is configured with
308 .BR CONFIG_KCMP .
309 .SH NOTES
310 See
311 .BR clone (2)
312 for some background information on the shared resources
313 referred to on this page.
314 .SH EXAMPLES
315 The program below uses
316 .BR kcmp ()
317 to test whether pairs of file descriptors refer to
318 the same open file description.
319 The program tests different cases for the file descriptor pairs,
320 as described in the program output.
321 An example run of the program is as follows:
322 .P
323 .in +4n
324 .EX
325 .RB $ " ./a.out" ;
326 Parent PID is 1144
327 Parent opened file on FD 3
328 \&
329 PID of child of fork() is 1145
330 Compare duplicate FDs from different processes:
331 kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same
332 Child opened file on FD 4
333 Compare FDs from distinct open()s in same process:
334 kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different
335 Child duplicated FD 3 to create FD 5
336 Compare duplicated FDs in same process:
337 kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same
338 .EE
339 .in
340 .SS Program source
341 \&
342 .\" SRC BEGIN (kcmp.c)
343 .EX
344 #define _GNU_SOURCE
345 #include <err.h>
346 #include <fcntl.h>
347 #include <linux/kcmp.h>
348 #include <stdint.h>
349 #include <stdio.h>
350 #include <stdlib.h>
351 #include <sys/syscall.h>
352 #include <sys/types.h>
353 #include <sys/wait.h>
354 #include <unistd.h>
355 \&
356 static int
357 kcmp(pid_t pid1, pid_t pid2, int type,
358 unsigned long idx1, unsigned long idx2)
359 {
360 return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2);
361 }
362 \&
363 static void
364 test_kcmp(char *msg, pid_t pid1, pid_t pid2, int fd_a, int fd_b)
365 {
366 printf("\[rs]t%s\[rs]n", msg);
367 printf("\[rs]t\[rs]tkcmp(%jd, %jd, KCMP_FILE, %d, %d) ==> %s\[rs]n",
368 (intmax_t) pid1, (intmax_t) pid2, fd_a, fd_b,
369 (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ?
370 "same" : "different");
371 }
372 \&
373 int
374 main(void)
375 {
376 int fd1, fd2, fd3;
377 static const char pathname[] = "/tmp/kcmp.test";
378 \&
379 fd1 = open(pathname, O_CREAT | O_RDWR, 0600);
380 if (fd1 == \-1)
381 err(EXIT_FAILURE, "open");
382 \&
383 printf("Parent PID is %jd\[rs]n", (intmax_t) getpid());
384 printf("Parent opened file on FD %d\[rs]n\[rs]n", fd1);
385 \&
386 switch (fork()) {
387 case \-1:
388 err(EXIT_FAILURE, "fork");
389 \&
390 case 0:
391 printf("PID of child of fork() is %jd\[rs]n", (intmax_t) getpid());
392 \&
393 test_kcmp("Compare duplicate FDs from different processes:",
394 getpid(), getppid(), fd1, fd1);
395 \&
396 fd2 = open(pathname, O_CREAT | O_RDWR, 0600);
397 if (fd2 == \-1)
398 err(EXIT_FAILURE, "open");
399 printf("Child opened file on FD %d\[rs]n", fd2);
400 \&
401 test_kcmp("Compare FDs from distinct open()s in same process:",
402 getpid(), getpid(), fd1, fd2);
403 \&
404 fd3 = dup(fd1);
405 if (fd3 == \-1)
406 err(EXIT_FAILURE, "dup");
407 printf("Child duplicated FD %d to create FD %d\[rs]n", fd1, fd3);
408 \&
409 test_kcmp("Compare duplicated FDs in same process:",
410 getpid(), getpid(), fd1, fd3);
411 break;
412 \&
413 default:
414 wait(NULL);
415 }
416 \&
417 exit(EXIT_SUCCESS);
418 }
419 .EE
420 .\" SRC END
421 .SH SEE ALSO
422 .BR clone (2),
423 .BR unshare (2)