KTRACE(9) | Kernel Developer's Manual | KTRACE(9)

# NAME

`ktrgenio`, `ktrnamei`, `ktrpsig`, `ktrsyscall`, `ktrsysret`, `KTRPOINT` — process tracing kernel interface

# SYNOPSIS

`#include <sys/param.h>`
`#include <sys/proc.h>`
`#include <sys/ktrace.h>`

`KTRPOINT`(struct proc *p, int type);

void
`ktrgenio`(struct proc *p, int fd, enum uio_rw rw, struct iovec *iov, int len, int error);

void
`ktrnamei`(struct proc *p, char *path);

void
`ktrpsig`(struct proc *p, int sig, sig_t action, int mask, int code, siginfo_t *si);

void
`ktrsyscall`(struct proc *p, register_t code, size_t argsize, register_t args[]);

void
`ktrsysret`(struct proc *p, register_t code, int error, register_t retval);

# DESCRIPTION

This interface is meant for kernel subsystems and machine dependent code to inform the user about the events occurring to the process should tracing of such be enabled using the ktrace(2) system call. Each of the functions (except for `KTRPOINT`) is meant for a particular type of event and is described below.

The `KTRPOINT`() macro should be used before calling any of the other tracing functions to verify that tracing for that particular type of events has been enabled. type must be a KTR_ value corresponding to a KTRFAC_ value described in ktrace(2).

`ktrgenio`() should be called for each generic input/output transaction that is described by the fd file descriptor, rw transaction type (consult sys/sys/uio.h for the `enum uio_rw` definition), iov input/output data vector, len size of the iov vector, and, lastly, error status of the transaction.

`ktrnamei`() should be called every time a namei(9) operation is performed over the path name.

`ktrpsig`() should be called for each signal sig posted for the traced process. The action taken is one of `SIG_DFL`, `SIG_IGN`, or `SIG_ERR` as described in the sigaction(2) document. mask is the current traced process' signal mask. Signal-specific code and siginfo_t structure as described in `<sys/siginfo.h>` are given in the code and si arguments respectively.

`ktrsyscall`() should be called for each system call number code executed with arguments in args of total count of argsize.

`ktrsysret`() should be called for a return from each system call number code and error number of error as described in errno(2) and a return value in retval that is syscall dependent.

# CODE REFERENCES

The process tracing facility is implemented in sys/kern/kern_ktrace.c.

# SEE ALSO

errno(2), ktrace(2), namei(9), syscall(9)

# HISTORY

The process tracing facility first appeared in 4.3BSD-Reno.

The `ktrace` section manual page appeared in OpenBSD 3.4.

December 13, 2023 | Debian