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