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