PRINTF(9) BSD Kernel Developer's Manual PRINTF(9)
NAME
printf, uprintf, tprintf, log -- formatted output conversion
SYNOPSIS
#include <sys/types.h>
#include <sys/systm.h>
int
printf(const char *fmt, ...);
void
tprintf(struct proc *p, int pri, const char *fmt, ...);
int
uprintf(const char *fmt, ...);
#include <sys/syslog.h>
void
log(int pri, const char *fmt, ...);
DESCRIPTION
The printf(9) family of functions are similar to the printf(3) family of functions. The different functions each use a different output
stream. The uprintf() function outputs to the current process' controlling tty, while printf() writes to the console as well as to the log-
ging facility. The tprintf() function outputs to the tty associated with the process p and the logging facility if pri is not -1. The log()
function sends the message to the kernel logging facility, using the log level as indicated by pri.
Each of these related functions use the fmt parameter in the same manner as printf(3). However, printf(9) adds two other conversion speci-
fiers.
The %b identifier expects two arguments: an int and a char *. These are used as a register value and a print mask for decoding bitmasks.
The print mask is made up of two parts: the base and the arguments. The base value is the output base expressed as an integer value; for
example, 10 gives octal and 20 gives hexadecimal. The arguments are made up of a sequence of bit identifiers. Each bit identifier begins
with an integer value which is the number of the bit (starting from 1) this identifier describes. The rest of the identifier is a string of
characters containing the name of the bit. The string is terminated by either the bit number at the start of the next bit identifier or NUL
for the last bit identifier.
The %D identifier is meant to assist in hexdumps. It requires two arguments: a u_char * pointer and a char * string. The memory pointed to
be the pointer is output in hexadecimal one byte at a time. The string is used as a delimiter between individual bytes. If present, a width
directive will specify the number of bytes to display. By default, 16 bytes of data are output.
The log() function uses syslog(3) level values LOG_DEBUG through LOG_EMERG for its pri parameter (mistakenly called 'priority' here). Alter-
natively, if a pri of -1 is given, the message will be appended to the last log message started by a previous call to log(). As these mes-
sages are generated by the kernel itself, the facility will always be LOG_KERN.
RETURN VALUES
The printf() and the uprintf() functions return the number of characters displayed.
EXAMPLES
This example demonstrates the use of the %b and %D conversion specifiers. The function
void
printf_test(void)
{
printf("reg=%b
", 3, "102BITTWO1BITONE
");
printf("out: %4D
", "AAAA", ":");
}
will produce the following output:
reg=3<BITTWO,BITONE>
out: 41:41:41:41
The call
log(LOG_DEBUG, "%s%d: been there.
", sc->sc_name, sc->sc_unit);
will add the appropriate debug message at priority ``kern.debug'' to the system log.
SEE ALSO
printf(3), syslog(3)
BSD
September 8, 2006 BSD
Check Out this Related Man Page
KPRINTF(9) BSD Kernel Developer's Manual KPRINTF(9)
NAME
device_printf, printf, snprintf, vprintf, vsnprintf, uprintf, ttyprintf, tprintf, aprint -- 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, ...);
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() and vsnprintf() write output to a string buffer. These four functions work similarly to their user
space counterparts, and are not described in detail here.
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 opera-
tions 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 counter-
parts 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 placed in the buffer buf. This is different to the user-space func-
tions of the same name.
The tprintf_open() function returns NULL if no terminal handle could be acquired.
SEE ALSO
printf(1), printf(3), snprintb(3), boot(8), autoconf(9), boothowto(9)
CODE REFERENCES
sys/kern/subr_prf.c
HISTORY
The sprintf() and vsprintf() unsized string formatting functions are supported for compatibility only, and are not documented here. New code
should use the size-limited snprintf() and vsnprintf() functions instead.
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.
BSD
January 21, 2011 BSD