KTRACE(2)

💅 KTRACE(2) — process tracing, but make it a vibe

okay so first things first: this is the <pink>KTRACE(2)</pink> page from the <purple>System Calls Manual</purple>, and it lives in the <mint>Standard C Library (libc, -lc)</mint> 💖 so yeah, it's a real one, bestie.

---

✨ NAME ✨

ktrace — process tracing 🕵️‍♀️ literally watching your processes do their thing

---

🎀 LIBRARY 🎀

Standard C Library (libc, -lc) — she's standard, she's C, she's in libc, and you link her with -lc. iykyk 🫶

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/time.h>
#include <sys/uio.h>
#include <sys/ktrace.h>

int
ktrace(const char *tracefile, int ops, int trpoints, int pid);

four includes, one function, zero drama. slay 💅

---

🦋 DESCRIPTION 🦋

The ktrace() system call enables or disables tracing of one or more processes. it's giving <hotpink>main character energy</hotpink> but for syscalls. 🔥

so like, important boundary check: <yellow>**users may only trace their own processes**. no spying on your roommate's processes, that's not cute. and only the superuser can trace setuid or setgid programs</yellow> — that one's a hard rule, don't test it, it will not go well for you 😭

the tracefile argument 🍓

The tracefile argument gives the pathname of the file to be used for tracing. and it has OPINIONS:

• the file <yellow>**must exist**` (you can't just point at vibes)
• it must be a <yellow>**regular file**` (no sockets, no chaos)
• it must be <yellow>**writable by the calling process**`

and here's the part that trips people up: all trace records are <hotpink>always appended</hotpink> to the file. always. so if you want to throw away the old trace data, you have to <red>**truncate the file to zero length yourself**` — it will not do it for you, she does not clean up after you 💀

small mercy tho: if tracing points are being disabled (that's KTROP_CLEAR down below 👇), tracefile may be NULL. ngl that's the one time NULL is acceptable here.

the ops argument 🔥

The ops argument specifies the requested ktrace operation. the defined operations are:

• KTROP_SET — Enable trace points specified in trpoints. (turn the lights on ✨)
• KTROP_CLEAR — Disable trace points specified in trpoints. (turn those specific lights off 🌙)
• KTROP_CLEARFILE — Stop all tracing. periodt. everything off, go home 💅
• KTRFLAG_DESCEND — The tracing change should apply to the specified process and all its current children. (yes, the whole friend group gets included 👯‍♀️)

the trpoints argument 🧚

The trpoints argument specifies the trace points of interest. the defined trace points are:

• KTRFAC_SYSCALL — Trace system calls. the classics 🎬
• KTRFAC_SYSRET — Trace return values from system calls. what did she say back 👀
• KTRFAC_NAMEI — Trace name lookup operations. path resolution tea ☕
• KTRFAC_GENIO — Trace all I/O (note that this option can generate much output). and bestie, when they say <red>**much**` output they mean it — this is the firehose option, prepare your disk 😭🔥
• KTRFAC_PSIG — Trace posted signals. 📮
• KTRFAC_CSW — Trace context switch points. the switching, the switching 🔄
• KTRFAC_USER — Trace application-specific events. your app's own little diary 📔
• KTRFAC_STRUCT — Trace certain data structures. structural, literally 🏗️
• KTRFAC_SYSCTL — Trace sysctls. ⚙️
• KTRFAC_PROCCTOR — Trace process construction. baby process being born 🍼 👶
• KTRFAC_PROCDTOR — Trace process destruction. rip in peace 🪦
• KTRFAC_CAPFAIL — Trace capability failures. the audacity was not permitted 💀
• KTRFAC_FAULT — Trace page faults. oops, not in memory 🙈
• KTRFAC_FAULTEND — Trace the end of page faults. and we're back 🎀
• KTRFAC_STRUCT_ARRAY — Trace arrays of certain data structures. the structures, but plural, in formation 👑
• KTRFAC_INHERIT — Inherit tracing to future children. passing the torch to the next generation 🫶

what a record actually looks like 📝

Each tracing event outputs a record composed of a generic header followed by a trace point specific structure. the generic header is:

struct ktr_header {
        int             ktr_len;                /* length of buf */
        short           ktr_type;               /* trace record type */
        pid_t           ktr_pid;                /* process id */
        char            ktr_comm[MAXCOMLEN+1];  /* command name */
        struct timeval  ktr_time;               /* timestamp */
        long            ktr_tid;                /* thread id */
};

okay so let's break down the header fields, because they all have jobs:

• The ktr_len field specifies the length of the ktr_type data that follows this header. so it's like, "how much stuff after me" 📏
• The ktr_pid and ktr_comm fields specify the process and command generating the record. who and what 👑
• The ktr_time field gives the time (with <purple>microsecond resolution</purple>) that the record was generated. precise, she's very precise ⏱️
• The ktr_tid field holds a thread id. the specific thread, bestie 🧵

then: The generic header is followed by ktr_len bytes of a ktr_type record. and the type specific records are defined in the <sys/ktrace.h> include file — go look, they're in there 🦋

---

⚙️ SYSCTL TUNABLES ⚙️

The following sysctl(8) tunables influence the behaviour of ktrace():

• kern.ktrace.genio_size — bounds the amount of data a traced I/O request will log to the trace file. (your emergency brake for KTRFAC_GENIO 🛑)
• kern.ktrace.request_pool — bounds the number of trace events being logged at a time. (a queue size, basically, so the kernel doesn't get overwhelmed 🚦)

also heads up: Sysctl tunables that control process debuggability (as determined by p_candebug(9)) also affect the operation of ktrace(). so permissions stuff elsewhere can absolutely come for you and block this. it's giving connected lore 🧚‍♀️

---

🌈 RETURN VALUES 🌈

The ktrace() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. classic 0 good, -1 bad, errno tells you why 😤

---

💀 ERRORS 💀

The ktrace() system call will fail if:

• [ENOTDIR] — A component of the path prefix is not a directory. (bestie you pointed at a file where a folder should be 😭)
• [ENAMETOOLONG] — A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. (that's a really long path, chill 🙈)
• [ENOENT] — The named tracefile does not exist. (it must exist! we said this! 💀)
• [EACCES] — Search permission is denied for a component of the path prefix. 🔒
• [ELOOP] — Too many symbolic links were encountered in translating the pathname. (the symlinks are giving infinite recursion, and not the slay kind 🌀)
• [EIO] — An I/O error occurred while reading from or writing to the file system. 💥
• [EINTEGRITY] — Corrupted data was detected while reading from the file system. (something's rotten and it's not the vibe ⚠️)
• [ENOSYS] — The kernel was not compiled with ktrace support. (they simply did not build it in 💔)

⚠️ lowkey important aside: A thread may be unable to log one or more tracing events due to a temporary shortage of resources. This condition is remembered by the kernel, and the next tracing request that succeeds will have the flag KTR_DROP set in its ktr_type field. so basically: if you ever see KTR_DROP, that means things got dropped earlier and the kernel remembered. don't ignore her 🫶

---

👑 SEE ALSO 👑

• kdump(1)
• ktrace(1)
• utrace(2)
• sysctl(8)
• p_candebug(9)

---

🌈 HISTORY 🌈

The ktrace() system call first appeared in <rainbow>4.4BSD. a legacy icon, honestly 💜

---

anyway that's the whole page bestie 🎀 10/10 would trace again. this version came to you from <pink>Debian</pink>, dated <purple>November 2, 2022</purple> — mwah, love u, go read your trace files ✨🦋💅