UTRACE(2)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💫 UTRACE(2) — bestie edition 💫

okay so real talk, this one lives in the System Calls Manual and it's from the Standard C Library (libc, -lc) — iykyk, that's the manual section number in the parens, not a vibe check result 🫶

🌸 NAME 🌸

utrace — drop a little user record into your ktrace log, no cap ✨

🎀 LIBRARY 🎀

Standard C Library (libc, -lc) — she's literally built in, you don't even have to link anything extra 💅

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

✨ DESCRIPTION ✨

So what this does: it adds a record to the process trace, and that info is supplied by you, the user. Iconic behavior honestly 👑

The record it makes contains len bytes straight from memory, pointed at by addr. That's the whole vibe.

⚠️ big one bestie: this call only has an effect if the calling process is being traced. If nobody's tracing you, it's giving "talking to a wall" 💀 nothing happens, no notes.

💖 RETURN VALUES 💖

Slayed successfully? You get the value 0 back 🎉

Otherwise you get -1, and the global variable errno gets set to tell you what went wrong. Fr fr, always check errno 😭

🔥 ERRORS 🔥

  • [EINVAL] — the specified data length len was bigger than KTR_USER_MAXLEN. bestie that's too much data, pick a smaller len 🙈
  • [ENOMEM] — insufficient memory to honor the request. she simply did not have the RAM to serve you 💀
  • [ENOSYS] — the currently running kernel was compiled without ktrace(2) support (that's the options KTRACE knob). so like… this whole syscall doesn't exist on your kernel, sorry 🫠

🌈 SEE ALSO 🌈

go read those next, they're the friend group 🧚💜

👑 HISTORY 👑

The utrace() system call first appeared in FreeBSD 2.2. a true vintage queen, we stan an elder 🌸

and that's the whole page bestie! 💖 this version was brought to you by the Debian crew, dated December 11, 2015 — mwah, go trace something cute 😘🦋

📦 where this page comes from