Copyright (c) 2024 The FreeBSD Foundation
This documentation was written by
Mark Johnston <markj@FreeBSD.org> under sponsorship
from the FreeBSD Foundation.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd January 23, 2024 .Dt KCMP 2 .Os .Sh NAME .Nm kcmp .Nd compare two kernel objects .Sh LIBRARY .Lb libc .Sh SYNOPSIS n unistd.h .Ft int .Fn kcmp "pid_t pid1" "pid_t pid2" "int type" "uintptr_t idx1" "uintptr_t idx2" .Sh DESCRIPTION The .Nm system call allows the caller to determine whether the two processes with PIDs .Fa pid1 and .Fa pid2 reference the same kernel object. The .Fa type parameter specifies the type of object, and .Fa idx1 and .Fa idx2 are identifiers which refer to some object in the context of process .Fa pid1 and .Fa pid2 , respectively.
p The following values for .Fa type may be specified: l -tag -width KCMP_FILE t Dv KCMP_FILE Compare two file descriptions referred to by file descriptors .Fa idx1 and .Fa idx2 . They may be equivalent if, for example, one of the descriptors was created by applying .Xr dup 2 to the other descriptor. t Dv KCMP_FILEOBJ Perform a .Dq deep comparison of the file descriptions referred to by file descriptors .Fa idx1 and .Fa idx2 . This tests whether the underlying object referred to by the file descriptions is the same. For example, if the same filesystem path is opened twice, the kernel will create two separate file descriptions to back the two file descriptors, but they will refer to the same underlying object, a .Xr vnode 9 . When compared using the .Dv KCMP_FILE type, these descriptors will be different, but using the .Dv KCMP_FILEOBJ type, they will be equal (assuming that the path was not unlinked in between the two opens). t Dv KCMP_FILES Determine whether the two processes share the same file descriptor table. This will be the case if one of the processes was created by .Xr rfork 2 without specifying the .Dv RFFDG flag. The .Fa idx1 and .Fa idx2 parameters are ignored. t Dv KCMP_SIGHAND Determine whether the two processes share the same signal handler table. This will be the case if one of the processes was created using the .Dv RFSIGSHARE flag to .Xr rfork 2 . The .Fa idx1 and .Fa idx2 parameters are ignored. t Dv KCMP_VM Determine whether the two processes share a virtual memory address space. This may be the case if one of the processes created the other using .Xr vfork 2 or .Xr rfork 2 with the .Dv RFMEM flag. The .Fa idx1 and .Fa idx2 parameters are ignored. .El The caller of .Nm must have permission to debug both processes, otherwise the system call will fail. .Sh RETURN VALUES If .Fa idx1 and .Fa idx2 refer to the same object, .Nm returns 0. If the object referred to by .Fa pid1 and .Fa idx1 is less or greater than the object referred to by .Fa pid2 and .Fa idx2 , .Nm returns the values 1 and 2, respectively. The order is defined internally by the kernel and is stable until the system reboots. If the two objects cannot be compared for some reason, .Nm returns 3. For example, if .Fa type is .Dv KCMP_FILEOBJ and .Fa idx1 and .Fa idx2 are different descriptor types, e.g., a socket and a file, then .Nm will return 3.
p If an error occurs, the value -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS .Nm may fail with the following errors: l -tag -width Er t Bq Er ENODEV .Dv KCMP_FILEOBJ was specified and .Fa idx1 refers to a file descriptor which does not implement a comparison operator. t Bq Er EINVAL The value of .Fa type is invalid. t Bq Er EBADF One of the file descriptors referred to by .Fa idx1 or .Fa idx2 is not valid. t Bq Er ESRCH One of the processes referred to by .Fa pid1 or .Fa pid2 does not exist or is not visible (e.g., due to jail restrictions). t Bq Er EPERM The caller does not have permission to access one of the processes referred to by .Fa pid1 or .Fa pid2 . .El .Sh SEE ALSO .Xr dup 2 , .Xr fcntl 2 , .Xr fork 2 , .Xr rfork 2 , .Xr vfork 2 .Sh STANDARDS The .Nm system call originated in Linux. This implementation aims to be source-compatible with the Linux implementation. .Fx implements only a subset of the possible values for .Fa type supported in Linux. More values may be added in the future. The .Dv KCMP_FILEOBJ type is a FreeBSD extension. .Sh HISTORY The .Nm function was introduced in .Fx 14.1 .