1.\" $NetBSD: kprintf.9,v 1.32 2012/11/21 17:18:11 christos Exp $ 2.\" 3.\" Copyright (c) 1998, 2002, 2007, 2011 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jeremy Cooper and by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd November 21, 2012 31.Dt KPRINTF 9 32.Os 33.Sh NAME 34.Nm device_printf , 35.Nm printf , 36.Nm snprintf , 37.Nm vprintf , 38.Nm vsnprintf , 39.Nm uprintf , 40.Nm ttyprintf , 41.Nm tprintf , 42.Nm aprint 43.Nd kernel formatted output conversion 44.Sh SYNOPSIS 45.In sys/systm.h 46.Ft void 47.Fn "device_printf" "device_t" "const char *format" "..." 48.Ft void 49.Fn "printf" "const char *format" "..." 50.Ft void 51.Fn "printf_nolog" "const char *format" "..." 52.Ft int 53.Fn "snprintf" "char *buf" "size_t size" "const char *format" "..." 54.Ft void 55.Fn "vprintf" "const char *format" "va_list ap" 56.Ft int 57.Fn "vsnprintf" "char *buf" "size_t size" "const char *format" "va_list ap" 58.Ft void 59.Fn "uprintf" "const char *format" "..." 60.Ft void 61.Fn "ttyprintf" "struct tty *tty" "const char *format" "..." 62.In sys/tprintf.h 63.Ft tpr_t 64.Fn "tprintf_open" "struct proc *p" 65.Ft void 66.Fn "tprintf" "tpr_t tpr" "const char *format" "..." 67.Ft void 68.Fn "tprintf_close" "tpr_t tpr" 69.Ft void 70.Fn "aprint_normal" "const char *format" "..." 71.Ft void 72.Fn "aprint_naive" "const char *format" "..." 73.Ft void 74.Fn "aprint_verbose" "const char *format" "..." 75.Ft void 76.Fn "aprint_debug" "const char *format" "..." 77.Ft void 78.Fn "aprint_error" "const char *format" "..." 79.Ft void 80.Fn "aprint_normal_dev" "device_t" "const char *format" "..." 81.Ft void 82.Fn "aprint_naive_dev" "device_t" "const char *format" "..." 83.Ft void 84.Fn "aprint_verbose_dev" "device_t" "const char *format" "..." 85.Ft void 86.Fn "aprint_debug_dev" "device_t" "const char *format" "..." 87.Ft void 88.Fn "aprint_error_dev" "device_t" "const char *format" "..." 89.Ft void 90.Fn "aprint_normal_ifnet" "struct ifnet *" "const char *format" "..." 91.Ft void 92.Fn "aprint_naive_ifnet" "struct ifnet *" "const char *format" "..." 93.Ft void 94.Fn "aprint_verbose_ifnet" "struct ifnet *" "const char *format" "..." 95.Ft void 96.Fn "aprint_debug_ifnet" "struct ifnet *" "const char *format" "..." 97.Ft void 98.Fn "aprint_error_ifnet" "struct ifnet *" "const char *format" "..." 99.Ft int 100.Fn "aprint_get_error_count" "void" 101.Sh DESCRIPTION 102The 103.Fn printf 104family of functions allows the kernel to send formatted messages to various 105output devices. 106The functions 107.Fn printf 108and 109.Fn vprintf 110send formatted strings to the system console. 111The 112.Fn device_printf 113function is identical to 114.Fn printf , 115except that it prefixes the log message with the corresponding 116device name. 117The 118.Fn printf_nolog 119function is identical to 120.Fn printf , 121except it does not send the data to the system log. 122The functions 123.Fn snprintf 124and 125.Fn vsnprintf 126write output to a string buffer. 127These four functions work similarly to their user space counterparts, 128and are not described in detail here. 129.Pp 130The functions 131.Fn uprintf 132and 133.Fn ttyprintf 134send formatted strings to the current process's controlling tty and a specific 135tty, respectively. 136.Pp 137The 138.Fn tprintf 139function sends formatted strings to a process's controlling tty, 140via a handle of type tpr_t. 141This allows multiple write operations to the tty with a guarantee that the 142tty will be valid across calls. 143A handle is acquired by calling 144.Fn tprintf_open 145with the target process as an argument. 146This handle must be closed with a matching call to 147.Fn tprintf_close . 148.Pp 149The functions 150.Fn aprint_normal , 151.Fn aprint_naive , 152.Fn aprint_verbose , 153.Fn aprint_debug , 154and 155.Fn aprint_error 156are intended to be used to print 157.Xr autoconf 9 158messages. 159Their verbosity depends on flags set in the 160.Va boothowto 161variable, through options passed during bootstrap; see 162.Xr boothowto 9 163and 164.Sx Interactive mode 165in 166.Xr boot 8 : 167.Bl -tag -width AB_VERBOSE 168.It Dv AB_SILENT 169silent mode, enabled by 170.Ic boot 171.Fl z . 172.It Dv AB_QUIET 173quiet mode, enabled by 174.Ic boot 175.Fl q . 176.It Dv AB_VERBOSE 177verbose mode, enabled by 178.Ic boot 179.Fl v . 180.It Dv AB_DEBUG 181debug mode, enabled by 182.Ic boot 183.Fl x . 184.El 185.Pp 186The 187.Fn aprint_* 188functions have the following behaviour, based on the above 189mentioned flags: 190.Bl -tag -width Xaprint_verboseXXX 191.It Fn aprint_normal 192Sends to the console unless 193.Dv AB_QUIET 194is set. 195Always sends to the log. 196.It Fn aprint_naive 197Sends to the console only if 198.Dv AB_QUIET 199is set. 200Never sends to the log. 201.It Fn aprint_verbose 202Sends to the console only if 203.Dv AB_VERBOSE 204is set. 205Always sends to the log. 206.It Fn aprint_debug 207Sends to the console and the log only if 208.Dv AB_DEBUG 209is set. 210.It Fn aprint_error 211Like 212.Fn aprint_normal , 213but also keeps track of the number of times called. 214This allows a subsystem to report the number of errors that occurred 215during a quiet or silent initialization phase. 216.El 217.Pp 218For the 219.Fn aprint_* 220functions there are two additional families of functions with the 221suffixes 222.Dv _dev 223and 224.Dv _ifnet 225which work like their counterparts without the suffixes, except that 226they take a 227.Ft device_t 228and 229.Ft struct ifnet * , 230respectively, as first argument, 231and prefix the log message with the 232corresponding device or interface name. 233.Pp 234The 235.Fn aprint_get_error_count 236function reports the number of errors and resets the counter to 0. 237.Pp 238If 239.Dv AB_SILENT 240is set, none of the autoconfiguration message printing routines send output 241to the console. 242The 243.Dv AB_VERBOSE 244and 245.Dv AB_DEBUG 246flags override 247.Dv AB_SILENT . 248.Sh RETURN VALUES 249The 250.Fn snprintf 251and 252.Fn vsnprintf 253functions return the number of characters that would have been placed 254in the buffer 255.Fa buf . 256if there was enough space in the buffer, not including the trailing 257.Dv NUL 258character used to terminate output strings like the user-space functions 259of the same name. 260.Pp 261The 262.Fn tprintf_open 263function returns 264.Dv NULL 265if no terminal handle could be acquired. 266.Sh SEE ALSO 267.Xr printf 1 , 268.Xr printf 3 , 269.Xr snprintb 3 , 270.Xr boot 8 , 271.Xr autoconf 9 , 272.Xr boothowto 9 273.Sh CODE REFERENCES 274.Pa sys/kern/subr_prf.c 275.Sh HISTORY 276The 277.Fn sprintf 278and 279.Fn vsprintf 280unsized string formatting functions are supported for compatibility only, 281and are not documented here. 282New code should use the size-limited 283.Fn snprintf 284and 285.Fn vsnprintf 286functions instead. 287.Pp 288In 289.Nx 1.5 290and earlier, 291.Fn printf 292supported more format strings than the user space 293.Fn printf . 294These nonstandard format strings are no longer supported. 295For the functionality provided by the former 296.Li %b 297format string, see 298.Xr snprintb 3 . 299.Pp 300The 301.Fn aprint_normal , 302.Fn aprint_naive , 303.Fn aprint_verbose , 304and 305.Fn aprint_debug 306functions first appeared in 307.Bsx . 308.Sh BUGS 309The 310.Fn uprintf 311and 312.Fn ttyprintf 313functions should be used sparingly, if at all. 314Where multiple lines of output are required to reach a process's 315controlling terminal, 316.Fn tprintf 317is preferred. 318