KPRINTF(9)

👑 KPRINTF(9) — kernel formatted output conversion, bestie edition 💅

okay so this is the KPRINTF(9) page from the Kernel Developer's Manual, and it's literally the entire lore of how the kernel prints stuff. formatted output conversion, but make it fashion ✨

---

🌸 NAME 🌸

device_printf, printf, printf_nolog, printf_nostamp, snprintf, vasprintf, vprintf, vsnprintf, uprintf, ttyprintf, tprintf_open, tprintf, tprintf_close, aprint_normal, aprint_naive, aprint_verbose, aprint_debug, aprint_error, aprint_normal_dev, aprint_naive_dev, aprint_verbose_dev, aprint_debug_dev, aprint_error_dev, aprint_normal_ifnet, aprint_naive_ifnet, aprint_verbose_ifnet, aprint_debug_ifnet, aprint_error_ifnet, aprint_get_error_count — kernel formatted output conversion 🫶

that's a lot of names, but they're all one big happy family, i promise.

---

✨ SYNOPSIS ✨

#include <sys/systm.h>

void
device_printf(device_t, const char *format, ...);

void
printf(const char *format, ...);

void
printf_nolog(const char *format, ...);

void
printf_nostamp(const char *format, ...);

int
snprintf(char *buf, size_t size, const char *format, ...);

int
vasprintf(char **buf, const char *format, va_list ap);

void
vprintf(const char *format, va_list ap);

int
vsnprintf(char *buf, size_t size, const char *format, va_list ap);

void
uprintf(const char *format, ...);

void
ttyprintf(struct tty *tty, const char *format, ...);

then, plot twist, a whole second header — the tprintf girlies get their own clubhouse:

#include <sys/tprintf.h>

tpr_t
tprintf_open(struct proc *p);

void
tprintf(tpr_t tpr, const char *format, ...);

void
tprintf_close(tpr_t tpr);

and now the autoconf roster, in all its glory 🎀

void
aprint_normal(const char *format, ...);

void
aprint_naive(const char *format, ...);

void
aprint_verbose(const char *format, ...);

void
aprint_debug(const char *format, ...);

void
aprint_error(const char *format, ...);

void
aprint_normal_dev(device_t, const char *format, ...);

void
aprint_naive_dev(device_t, const char *format, ...);

void
aprint_verbose_dev(device_t, const char *format, ...);

void
aprint_debug_dev(device_t, const char *format, ...);

void
aprint_error_dev(device_t, const char *format, ...);

void
aprint_normal_ifnet(struct ifnet *, const char *format, ...);

void
aprint_naive_ifnet(struct ifnet *, const char *format, ...);

void
aprint_verbose_ifnet(struct ifnet *, const char *format, ...);

void
aprint_debug_ifnet(struct ifnet *, const char *format, ...);

void
aprint_error_ifnet(struct ifnet *, const char *format, ...);

int
aprint_get_error_count(void);

---

💖 DESCRIPTION 💖

so. the printf() family of functions is how the kernel sends formatted messages out to various output devices. main character energy, truly. 🌈

printf() and vprintf() send formatted strings to the system console. 📺

device_printf() is identical to printf(), except it prefixes the log message with the corresponding device name. it's giving "hello, it's me, your device" energy.

printf_nolog() is identical to printf(), except it does not send the data to the system log. sneaky.

printf_nostamp() is identical to printf(), except it does not prefix the output with a timestamp. no clock, just vibes.

snprintf(), vasprintf(), and vsnprintf() write output to a string buffer instead. these five functions work similarly to their user space counterparts, and honestly? they're not described in detail here. iykyk.

🫶 heads up bestie: vasprintf() allocates memory with kmem_alloc(9), and it is the caller's responsibility to free the returned string with kmem_free(9). no cap, don't leak it.

uprintf() and ttyprintf() send formatted strings to the current process's controlling tty and a specific tty, respectively. two different ttys, two different jobs.

tprintf() sends formatted strings to a process's controlling tty, via a handle of type tpr_t. the whole point? it lets you do multiple write operations to the tty with a guarantee that the tty will be valid across calls. iconic, honestly. 💅

here's the flow: you acquire a handle by calling tprintf_open() with the target process as an argument. this handle must be closed with a matching call to tprintf_close(). matching. call. don't leave it hanging. 😭

---

🌼 the aprint girlies

the functions aprint_normal(), aprint_naive(), aprint_verbose(), aprint_debug(), and aprint_error() are intended to be used to print autoconf(9) messages. their verbosity depends on flags set in the boothowto variable, through options passed during bootstrap; see boothowto(9) and “Interactive mode” in boot(8):

• AB_SILENT — silent mode, enabled by boot -z.
• AB_QUIET — quiet mode, enabled by boot -q.
• AB_VERBOSE — verbose mode, enabled by boot -v.
• AB_DEBUG — debug mode, enabled by boot -x.

the aprint_*() functions have the following behaviour, based on the above mentioned flags 👇

• aprint_normal() — sends to the console unless AB_QUIET is set. always sends to the log. dependable queen.
• aprint_naive() — sends to the console only if AB_QUIET is set. never sends to the log. mysterious.
• aprint_verbose() — sends to the console only if AB_VERBOSE is set. always sends to the log. yapper energy.
• aprint_debug() — sends to the console and the log only if AB_DEBUG is set. exclusive club.
• aprint_error() — like aprint_normal(), but it also keeps track of the number of times called. this allows a subsystem to report the number of errors that occurred during a quiet or silent initialization phase. she's keeping receipts, bestie 🧾

---

🦋 the _dev and _ifnet suffixes

for the aprint_*() functions there are two additional families of functions with the suffixes _dev and _ifnet which work like their counterparts without the suffixes, except that they take a device_t and struct ifnet *, respectively, as first argument, and prefix the log message with the corresponding device or interface name. so basically, they're the same but with a name tag attached 🏷️

and aprint_get_error_count() reports the number of errors and resets the counter to 0. girlboss move: report + reset, in one call.

---

💀 the silent-mode plot twist

if AB_SILENT is set, none of the autoconfiguration message printing routines send output to the console. like, none of them. silence.

but — the AB_VERBOSE and AB_DEBUG flags override AB_SILENT. so if a chatty flag is on, the silence gets cancelled. 🔥

---

🍓 RETURN VALUES 🍓

snprintf() and vsnprintf() return the number of characters that would have been placed in the buffer buf, if there was enough space in the buffer, not including the trailing NUL character used to terminate output strings like the user-space functions of the same name. yes, would have been. it counts the dream, not the reality 💭

tprintf_open() returns NULL if no terminal handle could be acquired. so like, check for NULL. please. 🙏

---

🧚 CODE REFERENCES 🧚

sys/kern/subr_prf.c

---

💜 SEE ALSO 💜

printf(1), printf(3), snprintb(3), boot(8), autoconf(9), boothowto(9) — go read them, they're all part of the same friend group 🫶

---

🎀 HISTORY 🎀

in NetBSD 1.5 and earlier, printf() supported more format strings than the user space printf(). these nonstandard format strings are no longer supported. rip to a real one 💀

for the functionality provided by the former %b format string, see snprintb(3).

the aprint_normal(), aprint_naive(), aprint_verbose(), and aprint_debug() functions first appeared in BSD/OS. okay, legacy icons 👑

---

🙈 BUGS 🙈

uprintf() and ttyprintf() should be used sparingly, if at all. like, girl, be careful. 😬

where multiple lines of output are required to reach a process's controlling terminal, tprintf() is preferred. use the handle girlies, they're safer. no cap.

---

⭐ so that's the whole tea — kernel formatted output conversion, fully documented, fully slay. now go forth and printf() responsibly. periodt. 💅✨

---

this page was brought to you by the Debian edition of the Kernel Developer's Manual, dated March 10, 2021 — mwah, xoxo 🫶💖