1.\" $NetBSD: kprintf.9,v 1.31 2011/07/17 20:54:35 joerg 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 January 21, 2011 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 placed in the buffer 254.Fa buf . 255This is different to the user-space functions of the same name. 256.Pp 257The 258.Fn tprintf_open 259function returns 260.Dv NULL 261if no terminal handle could be acquired. 262.Sh SEE ALSO 263.Xr printf 1 , 264.Xr printf 3 , 265.Xr snprintb 3 , 266.Xr boot 8 , 267.Xr autoconf 9 , 268.Xr boothowto 9 269.Sh CODE REFERENCES 270.Pa sys/kern/subr_prf.c 271.Sh HISTORY 272The 273.Fn sprintf 274and 275.Fn vsprintf 276unsized string formatting functions are supported for compatibility only, 277and are not documented here. 278New code should use the size-limited 279.Fn snprintf 280and 281.Fn vsnprintf 282functions instead. 283.Pp 284In 285.Nx 1.5 286and earlier, 287.Fn printf 288supported more format strings than the user space 289.Fn printf . 290These nonstandard format strings are no longer supported. 291For the functionality provided by the former 292.Li %b 293format string, see 294.Xr snprintb 3 . 295.Pp 296The 297.Fn aprint_normal , 298.Fn aprint_naive , 299.Fn aprint_verbose , 300and 301.Fn aprint_debug 302functions first appeared in 303.Bsx . 304.Sh BUGS 305The 306.Fn uprintf 307and 308.Fn ttyprintf 309functions should be used sparingly, if at all. 310Where multiple lines of output are required to reach a process's 311controlling terminal, 312.Fn tprintf 313is preferred. 314