1.\" $NetBSD: kprintf.9,v 1.27 2009/04/08 12:46:04 joerg Exp $ 2.\" 3.\" Copyright (c) 1998, 2002, 2007 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 September 24, 2007 31.Dt KPRINTF 9 32.Os 33.Sh NAME 34.Nm printf , 35.Nm snprintf , 36.Nm vprintf , 37.Nm vsnprintf , 38.Nm uprintf , 39.Nm ttyprintf , 40.Nm tprintf , 41.Nm aprint 42.Nd kernel formatted output conversion 43.Sh SYNOPSIS 44.In sys/systm.h 45.Ft void 46.Fn "printf" "const char *format" "..." 47.Ft void 48.Fn "printf_nolog" "const char *format" "..." 49.Ft int 50.Fn "snprintf" "char *buf" "size_t size" "const char *format" "..." 51.In machine/stdarg.h 52.Ft void 53.Fn "vprintf" "const char *format" "va_list ap" 54.Ft int 55.Fn "vsnprintf" "char *buf" "size_t size" "const char *format" "va_list ap" 56.Ft void 57.Fn "uprintf" "const char *format" "..." 58.Ft void 59.Fn "ttyprintf" "struct tty *tty" "const char *format" "..." 60.In sys/tprintf.h 61.Ft tpr_t 62.Fn "tprintf_open" "struct proc *p" 63.Ft void 64.Fn "tprintf" "tpr_t tpr" "const char *format" "..." 65.Ft void 66.Fn "tprintf_close" "tpr_t tpr" 67.Ft void 68.Fn "aprint_normal" "const char *format" "..." 69.Ft void 70.Fn "aprint_naive" "const char *format" "..." 71.Ft void 72.Fn "aprint_verbose" "const char *format" "..." 73.Ft void 74.Fn "aprint_debug" "const char *format" "..." 75.Ft void 76.Fn "aprint_error" "const char *format" "..." 77.Ft void 78.Fn "aprint_normal_dev" "device_t" "const char *format" "..." 79.Ft void 80.Fn "aprint_naive_dev" "device_t" "const char *format" "..." 81.Ft void 82.Fn "aprint_verbose_dev" "device_t" "const char *format" "..." 83.Ft void 84.Fn "aprint_debug_dev" "device_t" "const char *format" "..." 85.Ft void 86.Fn "aprint_error_dev" "device_t" "const char *format" "..." 87.Ft void 88.Fn "aprint_normal_ifnet" "struct ifnet *" "const char *format" "..." 89.Ft void 90.Fn "aprint_naive_ifnet" "struct ifnet *" "const char *format" "..." 91.Ft void 92.Fn "aprint_verbose_ifnet" "struct ifnet *" "const char *format" "..." 93.Ft void 94.Fn "aprint_debug_ifnet" "struct ifnet *" "const char *format" "..." 95.Ft void 96.Fn "aprint_error_ifnet" "struct ifnet *" "const char *format" "..." 97.Ft int 98.Fn "aprint_get_error_count" "void" 99.Sh DESCRIPTION 100The 101.Fn printf 102family of functions allows the kernel to send formatted messages to various 103output devices. 104The functions 105.Fn printf 106and 107.Fn vprintf 108send formatted strings to the system console. 109The 110.Fn printf_nolog 111function is identical to 112.Fn printf , 113except it does not send the data to the system log. 114The functions 115.Fn snprintf 116and 117.Fn vsnprintf 118write output to a string buffer. 119These four functions work similarly to their user space counterparts, 120and are not described in detail here. 121.Pp 122The functions 123.Fn uprintf 124and 125.Fn ttyprintf 126send formatted strings to the current process's controlling tty and a specific 127tty, respectively. 128.Pp 129The 130.Fn tprintf 131function sends formatted strings to a process's controlling tty, 132via a handle of type tpr_t. 133This allows multiple write operations to the tty with a guarantee that the 134tty will be valid across calls. 135A handle is acquired by calling 136.Fn tprintf_open 137with the target process as an argument. 138This handle must be closed with a matching call to 139.Fn tprintf_close . 140.Pp 141The functions 142.Fn aprint_normal , 143.Fn aprint_naive , 144.Fn aprint_verbose , 145.Fn aprint_debug , 146and 147.Fn aprint_error 148are intended to be used to print 149.Xr autoconf 9 150messages. 151Their verbosity depends on flags set in the 152.Dq boothowto 153variable, through options passed during bootstrap; see 154.Sx Interactive mode 155in 156.Xr boot 8 : 157.Bl -tag -width AB_VERBOSE 158.It Dv AB_SILENT 159silent mode, enabled by 160.Ic boot 161.Fl z . 162.It Dv AB_QUIET 163quiet mode, enabled by 164.Ic boot 165.Fl q . 166.It Dv AB_VERBOSE 167verbose mode, enabled by 168.Ic boot 169.Fl v . 170.It Dv AB_DEBUG 171debug mode, enabled by 172.Ic boot 173.Fl x . 174.El 175.Pp 176The 177.Fn aprint_* 178functions have the following behaviour, based on the above 179mentioned flags: 180.Bl -tag -width Xaprint_verboseXXX 181.It Fn aprint_normal 182Sends to the console unless 183.Dv AB_QUIET 184is set. 185Always sends to the log. 186.It Fn aprint_naive 187Sends to the console only if 188.Dv AB_QUIET 189is set. 190Never sends to the log. 191.It Fn aprint_verbose 192Sends to the console only if 193.Dv AB_VERBOSE 194is set. 195Always sends to the log. 196.It Fn aprint_debug 197Sends to the console and the log only if 198.Dv AB_DEBUG 199is set. 200.It Fn aprint_error 201Like 202.Fn aprint_normal , 203but also keeps track of the number of times called. 204This allows a subsystem to report the number of errors that occurred 205during a quiet or silent initialization phase. 206.El 207.Pp 208For the 209.Fn aprint_* 210functions there are two additional families of functions with the 211suffixes 212.Dv _dev 213and 214.Dv _ifnet 215which work like their counterparts without the suffixes, except that 216they take a 217.Ft device_t 218or 219.Ft struct ifnet * 220respectively as first argument and prefix the log message with the 221corresponding device or interface name. 222.Pp 223The 224.Fn aprint_get_error_count 225function reports the number of errors and resets the counter to 0. 226.Pp 227If 228.Dv AB_SILENT 229is set, none of the autoconfiguration message printing routines send output 230to the console. 231The 232.Dv AB_VERBOSE 233and 234.Dv AB_DEBUG 235flags override 236.Dv AB_SILENT . 237.Sh RETURN VALUES 238The 239.Fn snprintf 240and 241.Fn vsnprintf 242functions return the number of characters placed in the buffer 243.Fa buf . 244This is different to the user-space functions of the same name. 245.Pp 246The 247.Fn tprintf_open 248function returns 249.Dv NULL 250if no terminal handle could be acquired. 251.Sh SEE ALSO 252.Xr printf 1 , 253.Xr printf 3 , 254.Xr snprintb 3 , 255.Xr boot 8 , 256.Xr autoconf 9 257.Sh CODE REFERENCES 258.Pa sys/kern/subr_prf.c 259.Sh HISTORY 260The 261.Fn sprintf 262and 263.Fn vsprintf 264unsized string formatting functions are supported for compatibility only, 265and are not documented here. 266New code should use the size-limited 267.Fn snprintf 268and 269.Fn vsnprintf 270functions instead. 271.Pp 272In 273.Nx 1.5 274and earlier, 275.Fn printf 276supported more format strings than the user space 277.Fn printf . 278These nonstandard format strings are no longer supported. 279For the functionality provided by the former 280.Li %b 281format string, see 282.Xr snprintb 3 . 283.Pp 284The 285.Fn aprint_normal , 286.Fn aprint_naive , 287.Fn aprint_verbose , 288and 289.Fn aprint_debug 290functions first appeared in 291.Bsx . 292.Sh BUGS 293The 294.Fn uprintf 295and 296.Fn ttyprintf 297functions should be used sparingly, if at all. 298Where multiple lines of output are required to reach a process's 299controlling terminal, 300.Fn tprintf 301is preferred. 302