NAME
device_printf,
printf,
printf_nolog,
snprintf,
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,
...);
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
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
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.