NAME
printf, snprintf,
vprintf, vsnprintf,
uprintf, ttyprintf,
db_printf, db_vprintf
— kernel formatted output
conversion
SYNOPSIS
#include
<sys/types.h>
#include <sys/systm.h>
int
printf(const char *format,
...);
int
snprintf(char *buf,
size_t size, const char *format,
...);
int
vprintf(const char *format,
va_list ap);
int
vsnprintf(char *buf,
size_t size, const char *fmt,
va_list ap);
void
uprintf(const char *format,
...);
void
ttyprintf(struct tty *tty,
const char *format, ...);
#include
<ddb/db_output.h>
void
db_printf(const
char *format,
...);
void
db_vprintf(const
char *format, va_list
ap);
DESCRIPTION
The
printf(),
snprintf(),
vprintf(),
vsnprintf(),
uprintf(),
ttyprintf(),
db_printf(),
and
db_vprintf()
functions allow the kernel to send formatted messages to various output
devices. The functions printf() and
vprintf() send formatted strings to the system
console and to the system log. The functions
uprintf() and ttyprintf()
send formatted strings to the current process's controlling tty and a
specific tty, respectively. The functions
db_printf() and db_vprintf()
send formatted strings to the ddb console, and are only used to implement
ddb(4).
Since each of these kernel functions is a variant of its user space counterpart, this page describes only the differences between the user space and kernel versions.
Only a subset of the user space conversion specification is available to the kernel version:
%[width][size]conversionRefer to printf(3) for functional details.
FORMAT OPTIONS
The kernel functions don't support as many formatting specifiers as their user space counterparts. In addition to the floating point formatting specifiers, the following integer type specifiers are not supported:
%hh- Argument of char type. This format specifier is
accepted by the kernel but will be handled as
%h. %j- Argument of intmax_t or uintmax_t type.
%t- Argument of ptrdiff_t type.
The kernel functions support some additional formatting specifiers:
%b- Bit field expansion. This format specifier is useful for decoding bit
fields in device registers. It displays an integer using a specified radix
(base) and an interpretation of the bits within that integer as though
they were flags. It requires two arguments from the argument vector, the
first argument being the bit field to be decoded (of type
int, unless a width modifier has been specified) and
the second being a decoding directive string.
The decoding directive string describes how the bitfield is to be interpreted and displayed. The first character of the string is a binary character representation of the output numeral base in which the bitfield will be printed before it is decoded. Recognized radix values (in C escape-character format) are
\10(octal),\12(decimal), and\20(hexadecimal).The remaining characters in the decoding directive string are interpreted as a list of bit-position–description pairs. A bit-position–description pair begins with a binary character value that represents the position of the bit being described. A bit position value of one describes the least significant bit. Whereas a position value of 32 (octal 40, hexadecimal 20, the ASCII space character) describes the most significant bit.
To deal with more than 32 bits, the characters 128 (octal 200, hexadecimal 80) through 255 (octal 377, hexadecimal FF) are used. The value 127 is subtracted from the character to determine the bit position (1 is least significant, and 128 is most significant).
The remaining characters in a bit-position–description pair are the characters to print should the bit being described be set. Description strings are delimited by the next bit position value character encountered (distinguishable by its value being ≤ 32 or ≥ 128), or the end of the decoding directive string itself.
RETURN VALUES
The printf() and
vprintf() functions return the number of characters
printed.
The snprintf() and
vsnprintf() functions return the number of
characters that would have been put into the buffer
buf if the size were
unlimited.
EXAMPLES
Use of the %b format specifier for
decoding device registers.
printf("reg=%b\n", 3, "\10\2BITTWO\1BITONE")
⇒ "reg=3<BITTWO,BITONE>"
printf("enablereg=%b\n", 0xe860,
"\20\x10NOTBOOT\x0fFPP\x0eSDVMA\x0cVIDEO"
"\x0bLORES\x0aFPA\x09DIAG\x07CACHE"
"\x06IOCACHE\x05LOOPBACK\x04DBGCACHE")
⇒ "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"
CODE REFERENCES
sys/kern/subr_prf.c