Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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

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

     void
     printf_nostamp(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 printf_nostamp() function is identical to printf(), except it
     does not prefix the output with a timestamp.  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.

NetBSD 10.99                    March 10, 2021                    NetBSD 10.99