KPRINTF(9)

NAME
printf, sprintf, vprintf, uprintf, ttyprintf - kernel formatted output conversion

SYNOPSIS
#include <sys/systm.h>
void
printf(const char *format, ...);
int
sprintf(char *buf, const char *format, ...);
void
vprintf(const char *format, va_list ap);
void
uprintf(const char *format, ...);
void
ttyprintf(struct tty *tty, const char *format, ...);

DESCRIPTION
The printf(), sprintf(), vprintf(), uprintf(), and ttyprintf() functions allow the kernel to send formatted messages to various output devices. The functions printf() and vprintf() send formatted strings to the system console. The functions uprintf() and ttyprintf() send formatted strings to the current process's controlling tty and a specific tty, respectively.

Since each of these kernel functions is a scaled down version of its user space counterpart ( printf(3), sprintf(3), and vprintf(3)), this page describes only the differences between the user space and kernel versions, rather than describing all of their functional details.

  FORMAT OPTIONS
In addition to the formatting specifiers that the user space functions accept in the format string format, the kernel functions accept the following format 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 (as an integer) 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.

    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 the end of the decoding directive string itself.

%:  Inline format continuation. This format specifier allows for recursive formatted output. Its argument is the new formatting string to obey and the argument which follows it is a va_list argument vector from which to obtain the data to be formatted.

%r  Integer value using current DDB radix. This format specifier is only availble in kernels enabled with the DDB debugger. ( See ddb(4)). Displays an integer using the current DDB radix.

%z  Signed hexadecimal with ‘0x’ prefix. This format specifier is only available in kernels enabled with the DDB debugger. ( See ddb(4)). Displays a signed integer using the C-style hexadecimal constant format.

RETURN VALUES
The sprintf() function returns the number of characters it placed in the buffer buf.

EXAMPLES
An example 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>"

An example use of the %: format specifier for recursive formatting.

    void
    bail(char *fmt, ...)
    {
            va_list ap;
            va_start (ap, fmt);
            printf("bailing out: %:\n", fmt, ap);
            va_end(ap);
    }
    bail("descriptor %d is invalid.", 5)
    ⇒ "bailing out: descriptor 5 is invalid"

SEE ALSO
printf(3), printf(1), ddb(4), tprintf(9)

CODE REFERENCES
sys/kern/subr_prf.c

BUGS
The %b format specifier cannot be used to decode integers greater than 32 bits in size. The uprintf() and ttyprintf() functions should be used sparingly, if at all.