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 2017-03-13 "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 .B #include <linux/kcmp.h>
  34
  35 .BI "int kcmp(pid_t " pid1 ", pid_t " pid2 ", int " type ,
  36 .BI "         unsigned long " idx1 ", unsigned long "  idx2 );
  37 .fi
  38
  39 .IR Note :
  40 There is no glibc wrapper for this system call; see NOTES.
  41 .SH DESCRIPTION
  42 The
  43 .BR kcmp ()
  44 system call can be used to check whether the two processes identified by
  45 .I pid1
  46 and
  47 .I pid2
  48 share a kernel resource such as virtual memory, file descriptors,
  49 and so on.
  50
  51 Permission to employ
  52 .BR kcmp ()
  53 is governed by ptrace access mode
  54 .B PTRACE_MODE_READ_REALCREDS
  55 checks against both
  56 .I pid1
  57 and
  58 .IR pid2 ;
  59 see
  60 .BR ptrace (2).
  61
  62 The
  63 .I type
  64 argument specifies which resource is to be compared in the two processes.
  65 It has one of the following values:
  66 .TP
  67 .BR KCMP_FILE
  68 Check whether a file descriptor
  69 .I idx1
  70 in the process
  71 .I pid1
  72 refers to the same open file description (see
  73 .BR open (2))
  74 as file descriptor
  75 .I idx2
  76 in the process
  77 .IR pid2 .
  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)).
  85 .TP
  86 .BR KCMP_FILES
  87 Check whether the processes share the same set of open file descriptors.
  88 The arguments
  89 .I idx1
  90 and
  91 .I idx2
  92 are ignored.
  93 See the discussion of the
  94 .BR CLONE_FILES
  95 flag in
  96 .BR clone (2).
  97 .TP
  98 .BR KCMP_FS
  99 Check whether the processes share the same filesystem information
 100 (i.e., file mode creation mask, working directory, and filesystem root).
 101 The arguments
 102 .I idx1
 103 and
 104 .I idx2
 105 are ignored.
 106 See the discussion of the
 107 .BR CLONE_FS
 108 flag in
 109 .BR clone (2).
 110 .TP
 111 .BR KCMP_IO
 112 Check whether the processes share I/O context.
 113 The arguments
 114 .I idx1
 115 and
 116 .I idx2
 117 are ignored.
 118 See the discussion of the
 119 .BR CLONE_IO
 120 flag in
 121 .BR clone (2).
 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.
 130 See the discussion of the
 131 .BR CLONE_SIGHAND
 132 flag in
 133 .BR clone (2).
 134 .TP
 135 .BR KCMP_SYSVSEM
 136 Check whether the processes share the same
 137 list of System\ V semaphore undo operations.
 138 The arguments
 139 .I idx1
 140 and
 141 .I idx2
 142 are ignored.
 143 See the discussion of the
 144 .BR CLONE_SYSVSEM
 145 flag in
 146 .BR clone (2).
 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.
 155 See the discussion of the
 156 .BR CLONE_VM
 157 flag in
 158 .BR clone (2).
 159 .PP
 160 Note the
 161 .BR kcmp ()
 162 is not protected against false positives which may occur if
 163 the processes are currently running.
 164 One should stop the processes by sending
 165 .BR SIGSTOP
 166 (see
 167 .BR signal (7))
 168 prior to inspection with this system call to obtain meaningful results.
 169 .SH RETURN VALUE
 170 The return value of a successful call to
 171 .BR kcmp ()
 172 is simply the result of arithmetic comparison
 173 of kernel pointers (when the kernel compares resources, it uses their
 174 memory addresses).
 175
 176 The easiest way to explain is to consider an example.
 177 Suppose that
 178 .I v1
 179 and
 180 .I v2
 181 are the addresses of appropriate resources, then the return value
 182 is one of the following:
 183 .RS 4
 184 .IP 0 4
 185 .I v1
 186 is equal to
 187 .IR v2 ;
 188 in other words, the two processes share the resource.
 189 .IP 1
 190 .I v1
 191 is less than
 192 .IR v2 .
 193 .IP 2
 194 .I v1
 195 is greater than
 196 .IR v2 .
 197 .IP 3
 198 .I v1
 199 is not equal to
 200 .IR v2 ,
 201 but ordering information is unavailable.
 202 .RE
 203 .PP
 204 On error, \-1 is returned, and
 205 .I errno
 206 is set appropriately.
 207
 208 .BR kcmp ()
 209 was designed to return values suitable for sorting.
 210 This is particularly handy if one needs to compare
 211 a large number of file descriptors.
 212 .SH ERRORS
 213 .TP
 214 .B EBADF
 215 .I type
 216 is
 217 .B KCMP_FILE
 218 and
 219 .I fd1
 220 or
 221 .I fd2
 222 is not an open file descriptor.
 223 .TP
 224 .B EINVAL
 225 .I type
 226 is invalid.
 227 .TP
 228 .B EPERM
 229 Insufficient permission to inspect process resources.
 230 The
 231 .B CAP_SYS_PTRACE
 232 capability is required to inspect processes that you do not own.
 233 Other ptrace limitations may also apply, such as
 234 .BR CONFIG_SECURITY_YAMA ,
 235 which, when
 236 .I /proc/sys/kernel/yama/ptrace_scope
 237 is 2, limits
 238 .BR kcmp ()
 239 to child processes;
 240 see
 241 .BR ptrace (2).
 242 .TP
 243 .B ESRCH
 244 Process
 245 .I pid1
 246 or
 247 .I pid2
 248 does not exist.
 249 .SH VERSIONS
 250 The
 251 .BR kcmp ()
 252 system call first appeared in Linux 3.5.
 253 .SH CONFORMING TO
 254 .BR kcmp ()
 255 is Linux-specific and should not be used in programs intended to be portable.
 256 .SH NOTES
 257 Glibc does not provide a wrapper for this system call; call it using
 258 .BR syscall (2).
 259
 260 This system call is available only if the kernel was configured with
 261 .BR CONFIG_CHECKPOINT_RESTORE .
 262 The main use of the system call is for the
 263 checkpoint/restore in user space (CRIU) feature.
 264 The alternative to this system call would have been to expose suitable
 265 process information via the
 266 .BR proc (5)
 267 filesystem; this was deemed to be unsuitable for security reasons.
 268
 269 See
 270 .BR clone (2)
 271 for some background information on the shared resources
 272 referred to on this page.
 273 .SH EXAMPLE
 274 The program below uses
 275 .BR kcmp ()
 276 to test whether pairs of file descriptors refer to
 277 the same open file description.
 278 The program tests different cases for the file descriptor pairs,
 279 as described in the program output.
 280 An example run of the program is as follows:
 281
 282 .nf
 283 .in +4n
 284 $ \fB./a.out\fP
 285 Parent PID is 1144
 286 Parent opened file on FD 3
 287
 288 PID of child of fork() is 1145
 289         Compare duplicate FDs from different processes:
 290                 kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same
 291 Child opened file on FD 4
 292         Compare FDs from distinct open()s in same process:
 293                 kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different
 294 Child duplicated FD 3 to create FD 5
 295         Compare duplicated FDs in same process:
 296                 kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same
 297 .in
 298 .fi
 299 .SS Program source
 300 \&
 301 .nf
 302 #define _GNU_SOURCE
 303 #include <sys/syscall.h>
 304 #include <sys/wait.h>
 305 #include <sys/stat.h>
 306 #include <stdlib.h>
 307 #include <stdio.h>
 308 #include <unistd.h>
 309 #include <fcntl.h>
 310 #include <linux/kcmp.h>
 311
 312 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 313                         } while (0)
 314
 315 static int
 316 kcmp(pid_t pid1, pid_t pid2, int type,
 317      unsigned long idx1, unsigned long idx2)
 318 {
 319     return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2);
 320 }
 321
 322 static void
 323 test_kcmp(char *msg, id_t pid1, pid_t pid2, int fd_a, int fd_b)
 324 {
 325     printf("\\t%s\\n", msg);
 326     printf("\\t\\tkcmp(%ld, %ld, KCMP_FILE, %d, %d) ==> %s\\n",
 327             (long) pid1, (long) pid2, fd_a, fd_b,
 328             (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ?
 329                         "same" : "different");
 330 }
 331
 332 int
 333 main(int argc, char *argv[])
 334 {
 335     int fd1, fd2, fd3;
 336     char pathname[] = "/tmp/kcmp.test";
 337
 338     fd1 = open(pathname, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR);
 339     if (fd1 == \-1)
 340         errExit("open");
 341
 342     printf("Parent PID is %ld\\n", (long) getpid());
 343     printf("Parent opened file on FD %d\\n\\n", fd1);
 344
 345     switch (fork()) {
 346     case \-1:
 347         errExit("fork");
 348
 349     case 0:
 350         printf("PID of child of fork() is %ld\\n", (long) getpid());
 351
 352         test_kcmp("Compare duplicate FDs from different processes:",
 353                 getpid(), getppid(), fd1, fd1);
 354
 355         fd2 = open(pathname, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR);
 356         if (fd2 == \-1)
 357             errExit("open");
 358         printf("Child opened file on FD %d\\n", fd2);
 359
 360         test_kcmp("Compare FDs from distinct open()s in same process:",
 361                 getpid(), getpid(), fd1, fd2);
 362
 363         fd3 = dup(fd1);
 364         if (fd3 == \-1)
 365             errExit("dup");
 366         printf("Child duplicated FD %d to create FD %d\\n", fd1, fd3);
 367
 368         test_kcmp("Compare duplicated FDs in same process:",
 369                 getpid(), getpid(), fd1, fd3);
 370         break;
 371
 372     default:
 373         wait(NULL);
 374     }
 375
 376     exit(EXIT_SUCCESS);
 377 }
 378 .fi
 379 .SH SEE ALSO
 380 .BR clone (2),
 381 .BR unshare (2)