UTRACE(2)

✨ UTRACE 💅 — the manual page, bestie edition ✨

okay so you found yourself in section 2 of the manual (system calls, the spicy stuff), and this one's called utrace. she's a Debian-flavoured page, dated December 11, 2015, and she's about to insert a user record in the ktrace log. yes, that's the whole vibe. let's go 🫶

---

🌸 NAME 🌸

utrace — insert user record in ktrace log

like. that's it. that's the job. she adds your little custom note into the trace log and then dips. iconic behaviour honestly 💖

---

🎀 LIBRARY 🎀

Standard C Library (libc, -lc)

so you link with -lc, which... bestie, you were already doing that. free of charge. no extra fees. slay ✨

---

🦋 SYNOPSIS 🦋

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

int
utrace(const void *addr, size_t len);

look at all those includes. four of them. she's high maintenance but she's worth it, fr fr 💅

---

💜 DESCRIPTION 💜

So the way this works: utrace() adds a record to the process trace with information supplied by you, the user. not the kernel, not some mystery process — you. main character energy, honestly 👑

The record contains len bytes from the memory pointed to by addr. that's it. that's the payload. you point at some bytes, you say how many, she scoops them up and tucks them into the trace log like a little gift 🎁

BIG IMPORTANT CAVEAT: this call only has an effect if the calling process is being traced. so if nobody's watching you, bestie, this does literally nothing. no trace, no record. vibe check: failed. 😭

---

🌈 RETURN VALUES 🌈

Upon successful completion, the value 0 is returned 🎉

otherwise the value -1 is returned, and the global variable errno is set to indicate the error. so check errno, she's always telling you what went wrong 💀

---

🔥 ERRORS 🔥

• [EINVAL] — the specified data length len was bigger than KTR_USER_MAXLEN. you tried to hand her too much. she said no. respect the limit 🚫
• [ENOMEM] — insufficient memory to honor the request. the machine is out of room, not your fault, but still, ouch 😭
• [ENOSYS] — the currently running kernel was compiled without ktrace(2) support (options KTRACE). so like, the feature just isn't in this kernel. nothing you can do from here, the kernel simply said "not today" 💀

---

🧚 SEE ALSO 🧚

kdump(1), ktrace(1), truss(1), ktrace(2), sysdecode_utrace(3)

the whole friend group!! go read them, they're all connected, iykyk 💖

---

⭐ HISTORY ⭐

The utrace() system call first appeared in FreeBSD 2.2. she's been around. she's a veteran. a legend, even 👑

---

and that's the page!! this one came from the Debian crew, dated December 11, 2015, and she is, as always, UTRACE(2) from the System Calls Manual. go trace something, bestie 🦋💖✨