man2/kcmp.2

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