mirror of https://github.com/mkerrisk/man-pages
kcmp.2: Substantial reworking/extension of Cyrill Gorcunov's page
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
aab0b384fd
commit
b73f9ed61d
205
man2/kcmp.2
205
man2/kcmp.2
|
@ -1,58 +1,107 @@
|
||||||
.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
|
.\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d
|
||||||
|
.\"
|
||||||
|
.TH KCMP 2 2012-12-19 "Linux" "Linux Programmer's Manual"
|
||||||
|
|
||||||
.SH NAME
|
.SH NAME
|
||||||
kcmp \- compare if two processes do share a particular kernel resource
|
kcmp \- compare two processes to determine if they share a kernel resource
|
||||||
|
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.nf
|
.nf
|
||||||
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
|
||||||
.B #include <unistd.h>
|
|
||||||
.B #include <linux/kcmp.h>
|
.B #include <linux/kcmp.h>
|
||||||
.BR "#include <sys/syscall.h> " "/* For SYS_xxx definitions */"
|
|
||||||
|
|
||||||
.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
|
.BI "int kcmp(pid_t " pid1 ", pid_t " pid2 ", int " type ,
|
||||||
|
.BI " unsigned long " idx1 ", unsigned long " idx2 );
|
||||||
|
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
.SH DESCRIPTION
|
.IR Note :
|
||||||
|
There is no glibc wrapper for this system call; see NOTES.
|
||||||
|
|
||||||
|
.SH DESCRIPTION
|
||||||
|
The
|
||||||
.BR kcmp ()
|
.BR kcmp ()
|
||||||
allows to find out if two processes identified by
|
system call can be used to check whether the two processes identified by
|
||||||
.I pid1
|
.I pid1
|
||||||
and
|
and
|
||||||
.I pid2
|
.I pid2
|
||||||
share kernel resources such as virtual memory, file descriptors, file system etc.
|
share a kernel resource such as virtual memory, file descriptors,
|
||||||
|
and so on.
|
||||||
|
|
||||||
The comparison
|
The
|
||||||
.I type
|
.I type
|
||||||
is one of the following
|
argument specifies which resource is to be compared in the two processes.
|
||||||
|
It has one of the following values:
|
||||||
|
|
||||||
|
.TP
|
||||||
.BR KCMP_FILE
|
.BR KCMP_FILE
|
||||||
determines whether a file descriptor
|
Check whether a file descriptor
|
||||||
.I idx1
|
.I idx1
|
||||||
in the first process is the same as another descriptor
|
in the process
|
||||||
|
.I pid1
|
||||||
|
refers to the same open file description (see
|
||||||
|
.BR open (2))
|
||||||
|
as file descriptor
|
||||||
.I idx2
|
.I idx2
|
||||||
in the second process
|
in the process
|
||||||
|
.IR pid2 .
|
||||||
.BR KCMP_VM
|
|
||||||
compares whether processes share address space
|
|
||||||
|
|
||||||
|
.TP
|
||||||
.BR KCMP_FILES
|
.BR KCMP_FILES
|
||||||
compares the file descriptor arrays to see whether the processes share all files
|
Check whether the process share the same set of open file descriptors.
|
||||||
|
The arguments
|
||||||
|
.I idx1
|
||||||
|
and
|
||||||
|
.I idx2
|
||||||
|
are ignored.
|
||||||
|
|
||||||
|
.TP
|
||||||
.BR KCMP_FS
|
.BR KCMP_FS
|
||||||
compares whether processes share the file system information (the current umask,
|
Check whether the processes share the same file system information
|
||||||
working directory, namespace root, etc)
|
(i.e., file mode creation mask, working directory, and file system root).
|
||||||
|
The arguments
|
||||||
.BR KCMP_SIGHAND
|
.I idx1
|
||||||
compares whether processes share a signal handlers table
|
and
|
||||||
|
.I idx2
|
||||||
|
are ignored.
|
||||||
|
|
||||||
|
.TP
|
||||||
.BR KCMP_IO
|
.BR KCMP_IO
|
||||||
compares whether processes do share I/O context,
|
Check whether the processes share I/O context.
|
||||||
used mainly for block I/O scheduling
|
The arguments
|
||||||
|
.I idx1
|
||||||
|
and
|
||||||
|
.I idx2
|
||||||
|
are ignored.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
.BR KCMP_SIGHAND
|
||||||
|
Check whether the processes share the same table of signal dispositions.
|
||||||
|
The arguments
|
||||||
|
.I idx1
|
||||||
|
and
|
||||||
|
.I idx2
|
||||||
|
are ignored.
|
||||||
|
|
||||||
|
.TP
|
||||||
.BR KCMP_SYSVSEM
|
.BR KCMP_SYSVSEM
|
||||||
compares the list of undo operations associated with SYSV semaphores
|
Check whether the processes share the same
|
||||||
|
list of System V semaphore undo operations.
|
||||||
|
The arguments
|
||||||
|
.I idx1
|
||||||
|
and
|
||||||
|
.I idx2
|
||||||
|
are ignored.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
.BR KCMP_VM
|
||||||
|
Check whether the processes share the same address space.
|
||||||
|
The arguments
|
||||||
|
.I idx1
|
||||||
|
and
|
||||||
|
.I idx2
|
||||||
|
are ignored.
|
||||||
|
|
||||||
|
.PP
|
||||||
Note the
|
Note the
|
||||||
.BR kcmp ()
|
.BR kcmp ()
|
||||||
is not protected against false positives which may have place if tasks are
|
is not protected against false positives which may have place if tasks are
|
||||||
|
@ -61,53 +110,111 @@ Which means one should stop tasks being inspected with this syscall to obtain
|
||||||
meaningful results.
|
meaningful results.
|
||||||
|
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
.B kcmp
|
The return value of a successful call to
|
||||||
was designed to return values suitable for sorting.
|
.BR kcmp ()
|
||||||
This is particularly handy when one have to compare
|
is simply the result of arithmetic comparison
|
||||||
a large number of file descriptors.
|
of kernel pointers (when the kernel compares resources, it uses their
|
||||||
|
|
||||||
The return value is merely a result of simple arithmetic comparison
|
|
||||||
of kernel pointers (when kernel compares resources, it uses their
|
|
||||||
memory addresses).
|
memory addresses).
|
||||||
|
|
||||||
The easiest way to explain is to consider an example.
|
The easiest way to explain is to consider an example.
|
||||||
Lets say
|
Suppose that
|
||||||
.I v1
|
.I v1
|
||||||
and
|
and
|
||||||
.I v2
|
.I v2
|
||||||
are the addresses of appropriate resources, then the return value
|
are the addresses of appropriate resources, then the return value
|
||||||
is one of the following
|
is one of the following:
|
||||||
|
|
||||||
.B 0
|
.RS 4
|
||||||
\-
|
.IP 0 4
|
||||||
.I v1
|
.I v1
|
||||||
is equal to
|
is equal to
|
||||||
.IR v2 ,
|
.IR v2 ;
|
||||||
in other words we have a shared resource here
|
in other words, the two processes share the resource.
|
||||||
|
|
||||||
.B 1
|
.IP 1
|
||||||
\-
|
|
||||||
.I v1
|
.I v1
|
||||||
is less than
|
is less than
|
||||||
.I v2
|
.IR v2 .
|
||||||
|
|
||||||
.B 2
|
.IP 2
|
||||||
\-
|
|
||||||
.I v1
|
.I v1
|
||||||
is greater than
|
is greater than
|
||||||
.I v2
|
.IR v2 .
|
||||||
|
|
||||||
.B 3
|
.IP 3
|
||||||
\-
|
|
||||||
.I v1
|
.I v1
|
||||||
is not equal to
|
is not equal to
|
||||||
.IR v2 ,
|
.IR v2 ,
|
||||||
but ordering information is unavailable.
|
but ordering information is unavailable.
|
||||||
|
.RE
|
||||||
|
|
||||||
On error, \-1 is returned, and errno is set appropriately.
|
.PP
|
||||||
|
On error, \-1 is returned, and
|
||||||
|
.I errno
|
||||||
|
is set appropriately.
|
||||||
|
|
||||||
|
.B kcmp ()
|
||||||
|
was designed to return values suitable for sorting.
|
||||||
|
This is particularly handy if one needs to compare
|
||||||
|
a large number of file descriptors.
|
||||||
|
|
||||||
|
.SH ERRORS
|
||||||
|
|
||||||
|
.TP
|
||||||
|
.B EBADF
|
||||||
|
.I type
|
||||||
|
is
|
||||||
|
.B KCMP_FILE
|
||||||
|
and
|
||||||
|
.I fd1
|
||||||
|
or
|
||||||
|
.I fd2
|
||||||
|
is not an open file descriptor.
|
||||||
|
.TP
|
||||||
|
.B EINVAL
|
||||||
|
.I type
|
||||||
|
is invalid.
|
||||||
|
.TP
|
||||||
|
.B EPERM
|
||||||
|
Insufficient permission to inspect process resources.
|
||||||
|
The
|
||||||
|
.B CAP_SYS_PTRACE
|
||||||
|
capability is required to inspect processes that you do not own.
|
||||||
|
.TP
|
||||||
|
.B ESRCH
|
||||||
|
Process
|
||||||
|
.I pid1
|
||||||
|
or
|
||||||
|
.I pid2
|
||||||
|
does not exist.
|
||||||
|
|
||||||
|
.SH VERSIONS
|
||||||
|
The
|
||||||
|
.BR kcmp ()
|
||||||
|
system call first appeared in Linux 3.5.
|
||||||
|
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
.BR kcmp ()
|
.BR kcmp ()
|
||||||
is Linux specific and should not be used in programs intended to be portable.
|
is Linux specific and should not be used in programs intended to be portable.
|
||||||
.SH "SEE ALSO"
|
|
||||||
|
.SH NOTES
|
||||||
|
Glibc does not provide a wrapper for this system call; call it using
|
||||||
|
.BR syscall (2).
|
||||||
|
|
||||||
|
This system call is available only if the kernel was configured with
|
||||||
|
.BR CONFIG_CHECKPOINT_RESTORE .
|
||||||
|
The main use of the system call is for the
|
||||||
|
checkpoint/restore in user space (CRIU) feature.
|
||||||
|
The alternative to this system call would have been to expose suitable
|
||||||
|
process information via the
|
||||||
|
.BR proc (5)
|
||||||
|
file system; this was deemed to be unsuitable for security reasons.
|
||||||
|
|
||||||
|
See
|
||||||
.BR clone (2)
|
.BR clone (2)
|
||||||
|
for some background information on the shared resources
|
||||||
|
referred to on this page.
|
||||||
|
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.BR clone (2),
|
||||||
|
.BR unshare (2)
|
||||||
|
|
Loading…
Reference in New Issue