NAME

kcmp — compare two kernel objects

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <unistd.h>

int
kcmp(pid_t pid1, pid_t pid2, int type, uintptr_t idx1, uintptr_t idx2);

DESCRIPTION

The kcmp system call allows the caller to determine whether the two processes with PIDs pid1 and pid2 reference the same kernel object. The type parameter specifies the type of object, and idx1 and idx2 are identifiers which refer to some object in the context of process pid1 and pid2, respectively.

The following values for type may be specified:

KCMP_FILE

Compare two file descriptions referred to by file descriptors idx1 and idx2. They may be equivalent if, for example, one of the descriptors was created by applying dup(2) to the other descriptor.

KCMP_FILEOBJ

Perform a “deep comparison” of the file descriptions referred to by file descriptors idx1 and 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 vnode(9). When compared using the KCMP_FILE type, these descriptors will be different, but using the KCMP_FILEOBJ type, they will be equal (assuming that the path was not unlinked in between the two opens).

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 rfork(2) without specifying the RFFDG flag. The idx1 and idx2 parameters are ignored.

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 RFSIGSHARE flag to rfork(2). The idx1 and idx2 parameters are ignored.

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 vfork(2) or rfork(2) with the RFMEM flag. The idx1 and idx2 parameters are ignored.

RETURN VALUES

If idx1 and idx2 refer to the same object, kcmp returns 0. If the object referred to by pid1 and idx1 is less or greater than the object referred to by pid2 and idx2, kcmp 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, kcmp returns 3. For example, if type is KCMP_FILEOBJ and idx1 and idx2 are different descriptor types, e.g., a socket and a file, then kcmp will return 3.

If an error occurs, the value -1 is returned and the global variable errno is set to indicate the error.

ERRORS

kcmp may fail with the following errors:

[ENODEV]

KCMP_FILEOBJ was specified and idx1 refers to a file descriptor which does not implement a comparison operator.

[EINVAL]

The value of type is invalid.

[EBADF]

One of the file descriptors referred to by idx1 or idx2 is not valid.

[ESRCH]

One of the processes referred to by pid1 or pid2 does not exist or is not visible (e.g., due to jail restrictions).

[EPERM]

The caller does not have permission to access one of the processes referred to by pid1 or pid2.

SEE ALSO

dup(2), fcntl(2), fork(2), rfork(2), vfork(2)

STANDARDS

The kcmp system call originated in Linux. This implementation aims to be source-compatible with the Linux implementation. FreeBSD implements only a subset of the possible values for type supported in Linux. More values may be added in the future. The KCMP_FILEOBJ type is a FreeBSD extension.

HISTORY

The kcmp function was introduced in FreeBSD 14.1.