KTRACE(9)

📦 in nixpkgs unstable

💫 KTRACE(9) — the process tracing kernel interface, bestie edition 💫

okay so this is a page from the Kernel Developer's Manual — yes, the kernel developer's manual, we're in the big leagues now 🫶 — and it's all about ktrgenio, ktrnamei, ktrpsig, ktrsyscall, ktrsysret, and KTRPOINT, aka the process tracing kernel interface. buckle up, this one's for the kernel girlies 💅

✨ 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);

like, look at all those includes. she's thriving 🌸

💖 DESCRIPTION 💖

so the whole vibe of this interface is: it exists for kernel subsystems and machine dependent code to keep the user in the loop about what's happening to a process — but only if tracing of that kind of event is actually turned on, which you do with the ktrace(2) system call ⭐. every one of these functions (except KTRPOINT, she's special, main character energy 👑) handles one specific type of event, and here's the breakdown:

  • KTRPOINT() — this macro. bestie. use her before you call any of the other tracing functions, because she's the vibe check that confirms tracing for that particular kind of event is even enabled ✅. type has to be a KTR_ value that lines up with a KTRFAC_ value described over in ktrace(2).
  • ktrgenio() — call this one for every generic input/output transaction. she takes the fd file descriptor, the rw transaction type (go peek at sys/sys/uio.h for the enum uio_rw definition 👀), the iov input/output data vector, len which is the size of the iov vector, and finally error, the status of the transaction. that's the whole squad right there 🎀
  • ktrnamei() — call her every single time a namei(9) operation gets performed over the path name. every. time. no cap 🦋
  • ktrpsig() — call this for each signal sig posted for the traced process. the action taken is one of SIG_DFL, SIG_IGN, or SIG_ERR, exactly as described in the sigaction(2) document. mask is the current traced process' signal mask. the signal-specific code and the siginfo_t structure (as described in <sys/siginfo.h>) get passed in through the code and si arguments respectively. she's giving very thorough 📋
  • ktrsyscall() — call her for each system call number code that gets executed, with the arguments in args, total count of argsize. 🔥
  • ktrsysret() — call her on the return from each system call number code, with the error number in error (as described in errno(2)) and a return value in retval that's syscall dependent — so like, don't come for her if retval looks different every time, that's literally the point 🙈

🔍 CODE REFERENCES 🔍

the process tracing facility is implemented in sys/kern/kern_ktrace.c. go read it, iykyk 💜

🌈 SEE ALSO 🌈

the whole friend group, love that for them 🫶

📜 HISTORY 📜

the process tracing facility first appeared in 4.3BSD-Reno. iconic behavior, honestly 👑

and the ktrace section manual page appeared in OpenBSD 3.4. slay 💅

mwah — this page came to you from Debian, dated December 13, 2023. go trace some processes, bestie, you've got this 🦋✨

📦 where this page comes from