diff options
Diffstat (limited to 'static/netbsd/man9/kprintf.9')
| -rw-r--r-- | static/netbsd/man9/kprintf.9 | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/static/netbsd/man9/kprintf.9 b/static/netbsd/man9/kprintf.9 new file mode 100644 index 00000000..2113828f --- /dev/null +++ b/static/netbsd/man9/kprintf.9 @@ -0,0 +1,341 @@ +.\" $NetBSD: kprintf.9,v 1.41 2025/01/12 20:16:34 rillig Exp $ +.\" +.\" Copyright (c) 1998, 2002, 2007, 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper and by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 10, 2021 +.Dt KPRINTF 9 +.Os +.Sh NAME +.Nm device_printf , +.Nm printf , +.Nm printf_nolog , +.Nm printf_nostamp , +.Nm snprintf , +.Nm vasprintf , +.Nm vprintf , +.Nm vsnprintf , +.Nm uprintf , +.Nm ttyprintf , +.Nm tprintf_open , +.Nm tprintf , +.Nm tprintf_close , +.Nm aprint_normal , +.Nm aprint_naive , +.Nm aprint_verbose , +.Nm aprint_debug , +.Nm aprint_error , +.Nm aprint_normal_dev , +.Nm aprint_naive_dev , +.Nm aprint_verbose_dev , +.Nm aprint_debug_dev , +.Nm aprint_error_dev , +.Nm aprint_normal_ifnet , +.Nm aprint_naive_ifnet , +.Nm aprint_verbose_ifnet , +.Nm aprint_debug_ifnet , +.Nm aprint_error_ifnet , +.Nm aprint_get_error_count +.Nd kernel formatted output conversion +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn device_printf "device_t" "const char *format" "..." +.Ft void +.Fn printf "const char *format" "..." +.Ft void +.Fn printf_nolog "const char *format" "..." +.Ft void +.Fn printf_nostamp "const char *format" "..." +.Ft int +.Fn snprintf "char *buf" "size_t size" "const char *format" "..." +.Ft int +.Fn vasprintf "char **buf" "const char *format" "va_list ap" +.Ft void +.Fn vprintf "const char *format" "va_list ap" +.Ft int +.Fn vsnprintf "char *buf" "size_t size" "const char *format" "va_list ap" +.Ft void +.Fn uprintf "const char *format" "..." +.Ft void +.Fn ttyprintf "struct tty *tty" "const char *format" "..." +.In sys/tprintf.h +.Ft tpr_t +.Fn tprintf_open "struct proc *p" +.Ft void +.Fn tprintf "tpr_t tpr" "const char *format" "..." +.Ft void +.Fn tprintf_close "tpr_t tpr" +.Ft void +.Fn aprint_normal "const char *format" "..." +.Ft void +.Fn aprint_naive "const char *format" "..." +.Ft void +.Fn aprint_verbose "const char *format" "..." +.Ft void +.Fn aprint_debug "const char *format" "..." +.Ft void +.Fn aprint_error "const char *format" "..." +.Ft void +.Fn aprint_normal_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_naive_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_verbose_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_debug_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_error_dev "device_t" "const char *format" "..." +.Ft void +.Fn aprint_normal_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_naive_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_verbose_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_debug_ifnet "struct ifnet *" "const char *format" "..." +.Ft void +.Fn aprint_error_ifnet "struct ifnet *" "const char *format" "..." +.Ft int +.Fn aprint_get_error_count "void" +.Sh DESCRIPTION +The +.Fn printf +family of functions allows the kernel to send formatted messages to various +output devices. +The functions +.Fn printf +and +.Fn vprintf +send formatted strings to the system console. +The +.Fn device_printf +function is identical to +.Fn printf , +except that it prefixes the log message with the corresponding +device name. +The +.Fn printf_nolog +function is identical to +.Fn printf , +except it does not send the data to the system log. +The +.Fn printf_nostamp +function is identical to +.Fn printf , +except it does not prefix the output with a timestamp. +The functions +.Fn snprintf , +.Fn vasprintf , +and +.Fn 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 +.Fn vasprintf +function allocates memory with +.Xr kmem_alloc 9 +and it is the caller's responsibility to free the returned string with +.Xr kmem_free 9 . +.Pp +The functions +.Fn uprintf +and +.Fn ttyprintf +send formatted strings to the current process's controlling tty and a specific +tty, respectively. +.Pp +The +.Fn 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 +.Fn tprintf_open +with the target process as an argument. +This handle must be closed with a matching call to +.Fn tprintf_close . +.Pp +The functions +.Fn aprint_normal , +.Fn aprint_naive , +.Fn aprint_verbose , +.Fn aprint_debug , +and +.Fn aprint_error +are intended to be used to print +.Xr autoconf 9 +messages. +Their verbosity depends on flags set in the +.Va boothowto +variable, through options passed during bootstrap; see +.Xr boothowto 9 +and +.Sx Interactive mode +in +.Xr boot 8 : +.Bl -tag -width AB_VERBOSE +.It Dv AB_SILENT +silent mode, enabled by +.Ic boot +.Fl z . +.It Dv AB_QUIET +quiet mode, enabled by +.Ic boot +.Fl q . +.It Dv AB_VERBOSE +verbose mode, enabled by +.Ic boot +.Fl v . +.It Dv AB_DEBUG +debug mode, enabled by +.Ic boot +.Fl x . +.El +.Pp +The +.Fn aprint_* +functions have the following behaviour, based on the above +mentioned flags: +.Bl -tag -width Xaprint_verboseXXX +.It Fn aprint_normal +Sends to the console unless +.Dv AB_QUIET +is set. +Always sends to the log. +.It Fn aprint_naive +Sends to the console only if +.Dv AB_QUIET +is set. +Never sends to the log. +.It Fn aprint_verbose +Sends to the console only if +.Dv AB_VERBOSE +is set. +Always sends to the log. +.It Fn aprint_debug +Sends to the console and the log only if +.Dv AB_DEBUG +is set. +.It Fn aprint_error +Like +.Fn 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. +.El +.Pp +For the +.Fn aprint_* +functions there are two additional families of functions with the +suffixes +.Dv _dev +and +.Dv _ifnet +which work like their counterparts without the suffixes, except that +they take a +.Ft device_t +and +.Ft struct ifnet * , +respectively, as first argument, +and prefix the log message with the +corresponding device or interface name. +.Pp +The +.Fn aprint_get_error_count +function reports the number of errors and resets the counter to 0. +.Pp +If +.Dv AB_SILENT +is set, none of the autoconfiguration message printing routines send output +to the console. +The +.Dv AB_VERBOSE +and +.Dv AB_DEBUG +flags override +.Dv AB_SILENT . +.Sh RETURN VALUES +The +.Fn snprintf +and +.Fn vsnprintf +functions return the number of characters that would have been placed +in the buffer +.Fa buf , +if there was enough space in the buffer, not including the trailing +.Dv NUL +character used to terminate output strings like the user-space functions +of the same name. +.Pp +The +.Fn tprintf_open +function returns +.Dv NULL +if no terminal handle could be acquired. +.Sh CODE REFERENCES +.Pa sys/kern/subr_prf.c +.Sh SEE ALSO +.Xr printf 1 , +.Xr printf 3 , +.Xr snprintb 3 , +.Xr boot 8 , +.Xr autoconf 9 , +.Xr boothowto 9 +.Sh HISTORY +In +.Nx 1.5 +and earlier, +.Fn printf +supported more format strings than the user space +.Fn printf . +These nonstandard format strings are no longer supported. +For the functionality provided by the former +.Li %b +format string, see +.Xr snprintb 3 . +.Pp +The +.Fn aprint_normal , +.Fn aprint_naive , +.Fn aprint_verbose , +and +.Fn aprint_debug +functions first appeared in +.Bsx . +.Sh BUGS +The +.Fn uprintf +and +.Fn ttyprintf +functions should be used sparingly, if at all. +Where multiple lines of output are required to reach a process's +controlling terminal, +.Fn tprintf +is preferred. |