KPRINTF(9)

KPRINTF(9) | Kernel Developer's Manual | KPRINTF(9)

# NAME

`device_printf`, `printf`, `printf_nolog`, `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

# SYNOPSIS

`#include <sys/systm.h>`

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

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

void
`printf_nolog`(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, ...);

`#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);

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

The `printf`() family of functions allows the kernel to send formatted messages to various output devices. The functions `printf`() and `vprintf`() send formatted strings to the system console. The `device_printf`() function is identical to `printf`(), except that it prefixes the log message with the corresponding device name. The `printf_nolog`() function is identical to `printf`(), except it does not send the data to the system log. The functions `snprintf`(), `vasprintf`(), and `vsnprintf`() write output to a string buffer. These five functions work similarly to their user space counterparts, and are not described in detail here. The `vasprintf`() function allocates memory with kmem_alloc(9) and it is the caller's responsibility to free the returned string with kmem_free(9).

The functions `uprintf`() and `ttyprintf`() send formatted strings to the current process's controlling tty and a specific tty, respectively.

The `tprintf`() function sends formatted strings to a process's controlling tty, via a handle of type tpr_t. This allows multiple write operations to the tty with a guarantee that the tty will be valid across calls. A handle is acquired by calling `tprintf_open`() with the target process as an argument. This handle must be closed with a matching call to `tprintf_close`().

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.
`aprint_naive`()
  Sends to the console only if `AB_QUIET` is set. Never sends to the log.
`aprint_verbose`()
  Sends to the console only if `AB_VERBOSE` is set. Always sends to the log.
`aprint_debug`()
  Sends to the console and the log only if `AB_DEBUG` is set.
`aprint_error`()
  Like `aprint_normal`(), but 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.

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.

The `aprint_get_error_count`() function reports the number of errors and resets the counter to 0.

If `AB_SILENT` is set, none of the autoconfiguration message printing routines send output to the console. The `AB_VERBOSE` and `AB_DEBUG` flags override `AB_SILENT`.

# RETURN VALUES

The `snprintf`() and `vsnprintf`() functions 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.

The `tprintf_open`() function returns `NULL` if no terminal handle could be acquired.

# CODE REFERENCES

sys/kern/subr_prf.c

# SEE ALSO

printf(1), printf(3), snprintb(3), boot(8), autoconf(9), boothowto(9)

# 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. 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.

# BUGS

The `uprintf`() and `ttyprintf`() functions should be used sparingly, if at all. Where multiple lines of output are required to reach a process's controlling terminal, `tprintf`() is preferred.

May 20, 2019 | NetBSD 9.5