]>
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 | .\" | |
3df541c0 | 28 | .TH KCMP 2 2016-07-17 "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> |
aab0b384 | 34 | |
9f1b9726 | 35 | .BI "int kcmp(pid_t " pid1 ", pid_t " pid2 ", int " type , |
b73f9ed6 | 36 | .BI " unsigned long " idx1 ", unsigned long " idx2 ); |
aab0b384 CG |
37 | .fi |
38 | ||
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. | |
aab0b384 | 50 | |
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). | |
61 | ||
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 . |
b73f9ed6 | 78 | .TP |
aab0b384 | 79 | .BR KCMP_FILES |
b73f9ed6 MK |
80 | Check whether the process share the same set of open file descriptors. |
81 | The arguments | |
82 | .I idx1 | |
83 | and | |
84 | .I idx2 | |
85 | are ignored. | |
b73f9ed6 | 86 | .TP |
aab0b384 | 87 | .BR KCMP_FS |
9ee4a2b6 MK |
88 | Check whether the processes share the same filesystem information |
89 | (i.e., file mode creation mask, working directory, and filesystem root). | |
b73f9ed6 MK |
90 | The arguments |
91 | .I idx1 | |
92 | and | |
93 | .I idx2 | |
94 | are ignored. | |
b73f9ed6 | 95 | .TP |
aab0b384 | 96 | .BR KCMP_IO |
b73f9ed6 MK |
97 | Check whether the processes share I/O context. |
98 | The arguments | |
99 | .I idx1 | |
100 | and | |
101 | .I idx2 | |
102 | are ignored. | |
b73f9ed6 MK |
103 | .TP |
104 | .BR KCMP_SIGHAND | |
105 | Check whether the processes share the same table of signal dispositions. | |
106 | The arguments | |
107 | .I idx1 | |
108 | and | |
109 | .I idx2 | |
110 | are ignored. | |
b73f9ed6 | 111 | .TP |
aab0b384 | 112 | .BR KCMP_SYSVSEM |
b73f9ed6 | 113 | Check whether the processes share the same |
efbfd7ec | 114 | list of System\ V semaphore undo operations. |
b73f9ed6 MK |
115 | The arguments |
116 | .I idx1 | |
117 | and | |
118 | .I idx2 | |
119 | are ignored. | |
b73f9ed6 MK |
120 | .TP |
121 | .BR KCMP_VM | |
122 | Check whether the processes share the same address space. | |
123 | The arguments | |
124 | .I idx1 | |
125 | and | |
126 | .I idx2 | |
127 | are ignored. | |
b73f9ed6 | 128 | .PP |
aab0b384 CG |
129 | Note the |
130 | .BR kcmp () | |
43a9c083 MK |
131 | is not protected against false positives which may occur if |
132 | the processes are currently running. | |
133 | One should stop the processes by sending | |
df2f284e SL |
134 | .BR SIGSTOP |
135 | (see | |
136 | .BR signal (7)) | |
6add864c | 137 | prior to inspection with this system call to obtain meaningful results. |
47297adb | 138 | .SH RETURN VALUE |
b73f9ed6 MK |
139 | The return value of a successful call to |
140 | .BR kcmp () | |
141 | is simply the result of arithmetic comparison | |
142 | of kernel pointers (when the kernel compares resources, it uses their | |
aab0b384 CG |
143 | memory addresses). |
144 | ||
145 | The easiest way to explain is to consider an example. | |
b73f9ed6 | 146 | Suppose that |
aab0b384 CG |
147 | .I v1 |
148 | and | |
149 | .I v2 | |
150 | are the addresses of appropriate resources, then the return value | |
b73f9ed6 | 151 | is one of the following: |
b73f9ed6 MK |
152 | .RS 4 |
153 | .IP 0 4 | |
aab0b384 CG |
154 | .I v1 |
155 | is equal to | |
b73f9ed6 MK |
156 | .IR v2 ; |
157 | in other words, the two processes share the resource. | |
b73f9ed6 | 158 | .IP 1 |
aab0b384 CG |
159 | .I v1 |
160 | is less than | |
b73f9ed6 | 161 | .IR v2 . |
b73f9ed6 | 162 | .IP 2 |
aab0b384 CG |
163 | .I v1 |
164 | is greater than | |
b73f9ed6 | 165 | .IR v2 . |
b73f9ed6 | 166 | .IP 3 |
aab0b384 CG |
167 | .I v1 |
168 | is not equal to | |
169 | .IR v2 , | |
170 | but ordering information is unavailable. | |
b73f9ed6 | 171 | .RE |
b73f9ed6 MK |
172 | .PP |
173 | On error, \-1 is returned, and | |
174 | .I errno | |
175 | is set appropriately. | |
176 | ||
0ae31c56 | 177 | .BR kcmp () |
b73f9ed6 MK |
178 | was designed to return values suitable for sorting. |
179 | This is particularly handy if one needs to compare | |
180 | a large number of file descriptors. | |
b73f9ed6 | 181 | .SH ERRORS |
b73f9ed6 MK |
182 | .TP |
183 | .B EBADF | |
184 | .I type | |
185 | is | |
186 | .B KCMP_FILE | |
187 | and | |
188 | .I fd1 | |
189 | or | |
190 | .I fd2 | |
191 | is not an open file descriptor. | |
192 | .TP | |
193 | .B EINVAL | |
194 | .I type | |
195 | is invalid. | |
196 | .TP | |
197 | .B EPERM | |
198 | Insufficient permission to inspect process resources. | |
199 | The | |
200 | .B CAP_SYS_PTRACE | |
5c1932ae | 201 | capability is required to inspect processes that you do not own. |
2a7b88af | 202 | Other ptrace limitations may also apply, such as |
8ec68b89 | 203 | .BR CONFIG_SECURITY_YAMA , |
164a3a92 | 204 | which, when |
5c1932ae | 205 | .I /proc/sys/kernel/yama/ptrace_scope |
164a3a92 | 206 | is 2, limits |
5c1932ae MK |
207 | .BR kcmp () |
208 | to child processes; | |
209 | see | |
210 | .BR ptrace (2). | |
b73f9ed6 MK |
211 | .TP |
212 | .B ESRCH | |
213 | Process | |
214 | .I pid1 | |
215 | or | |
216 | .I pid2 | |
217 | does not exist. | |
b73f9ed6 MK |
218 | .SH VERSIONS |
219 | The | |
220 | .BR kcmp () | |
221 | system call first appeared in Linux 3.5. | |
47297adb | 222 | .SH CONFORMING TO |
aab0b384 | 223 | .BR kcmp () |
76c637e1 | 224 | is Linux-specific and should not be used in programs intended to be portable. |
b73f9ed6 MK |
225 | .SH NOTES |
226 | Glibc does not provide a wrapper for this system call; call it using | |
227 | .BR syscall (2). | |
228 | ||
229 | This system call is available only if the kernel was configured with | |
230 | .BR CONFIG_CHECKPOINT_RESTORE . | |
231 | The main use of the system call is for the | |
232 | checkpoint/restore in user space (CRIU) feature. | |
233 | The alternative to this system call would have been to expose suitable | |
234 | process information via the | |
235 | .BR proc (5) | |
9ee4a2b6 | 236 | filesystem; this was deemed to be unsuitable for security reasons. |
b73f9ed6 MK |
237 | |
238 | See | |
aab0b384 | 239 | .BR clone (2) |
b73f9ed6 MK |
240 | for some background information on the shared resources |
241 | referred to on this page. | |
2e4eff1b MK |
242 | .SH EXAMPLE |
243 | The program below uses | |
244 | .BR kcmp () | |
245 | to test whether pairs of file descriptors refer to | |
246 | the same open file description. | |
247 | The program tests different cases for the file descriptor pairs, | |
248 | as described in the program output. | |
249 | An example run of the program is as follows: | |
250 | ||
251 | .nf | |
252 | .in +4n | |
253 | $ \fB./a.out\fP | |
254 | Parent PID is 1144 | |
255 | Parent opened file on FD 3 | |
256 | ||
257 | PID of child of fork() is 1145 | |
258 | Compare duplicate FDs from different processes: | |
259 | kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same | |
260 | Child opened file on FD 4 | |
261 | Compare FDs from distinct open()s in same process: | |
262 | kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different | |
263 | Child duplicated FD 3 to create FD 5 | |
264 | Compare duplicated FDs in same process: | |
265 | kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same | |
266 | .in | |
267 | .fi | |
268 | .SS Program source | |
269 | \& | |
270 | .nf | |
271 | #define _GNU_SOURCE | |
272 | #include <sys/syscall.h> | |
273 | #include <sys/wait.h> | |
274 | #include <sys/stat.h> | |
275 | #include <stdlib.h> | |
276 | #include <stdio.h> | |
277 | #include <unistd.h> | |
278 | #include <fcntl.h> | |
279 | #include <linux/kcmp.h> | |
280 | ||
281 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ | |
282 | } while (0) | |
283 | ||
284 | static int | |
285 | kcmp(pid_t pid1, pid_t pid2, int type, | |
286 | unsigned long idx1, unsigned long idx2) | |
287 | { | |
288 | return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2); | |
289 | } | |
290 | ||
291 | static void | |
292 | test_kcmp(char *msg, id_t pid1, pid_t pid2, int fd_a, int fd_b) | |
293 | { | |
294 | printf("\\t%s\\n", msg); | |
295 | printf("\\t\\tkcmp(%ld, %ld, KCMP_FILE, %d, %d) ==> %s\\n", | |
296 | (long) pid1, (long) pid2, fd_a, fd_b, | |
ac64534c | 297 | (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ? |
2e4eff1b MK |
298 | "same" : "different"); |
299 | } | |
300 | ||
301 | int | |
302 | main(int argc, char *argv[]) | |
303 | { | |
304 | int fd1, fd2, fd3; | |
305 | char pathname[] = "/tmp/kcmp.test"; | |
306 | ||
307 | fd1 = open(pathname, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR); | |
308 | if (fd1 == \-1) | |
309 | errExit("open"); | |
310 | ||
311 | printf("Parent PID is %ld\\n", (long) getpid()); | |
312 | printf("Parent opened file on FD %d\\n\\n", fd1); | |
313 | ||
314 | switch (fork()) { | |
315 | case \-1: | |
316 | errExit("fork"); | |
317 | ||
318 | case 0: | |
319 | printf("PID of child of fork() is %ld\\n", (long) getpid()); | |
320 | ||
321 | test_kcmp("Compare duplicate FDs from different processes:", | |
322 | getpid(), getppid(), fd1, fd1); | |
323 | ||
324 | fd2 = open(pathname, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR); | |
325 | if (fd2 == \-1) | |
326 | errExit("open"); | |
327 | printf("Child opened file on FD %d\\n", fd2); | |
328 | ||
329 | test_kcmp("Compare FDs from distinct open()s in same process:", | |
330 | getpid(), getpid(), fd1, fd2); | |
331 | ||
332 | fd3 = dup(fd1); | |
333 | if (fd3 == \-1) | |
334 | errExit("dup"); | |
335 | printf("Child duplicated FD %d to create FD %d\\n", fd1, fd3); | |
336 | ||
337 | test_kcmp("Compare duplicated FDs in same process:", | |
338 | getpid(), getpid(), fd1, fd3); | |
339 | break; | |
340 | ||
341 | default: | |
342 | wait(NULL); | |
343 | } | |
344 | ||
345 | exit(EXIT_SUCCESS); | |
346 | } | |
347 | .fi | |
47297adb | 348 | .SH SEE ALSO |
b73f9ed6 MK |
349 | .BR clone (2), |
350 | .BR unshare (2) |