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