1.\" $NetBSD: kprintf.9,v 1.23 2008/04/30 13:10:58 martin 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 autoconfiguration messages, and change 142their behavior based on flags in the 143.Dq boothowto 144variable: 145.Bl -tag -width "aprint_verbose()" 146.It Fn aprint_normal 147Sends to the console unless 148.Dv AB_QUIET 149is set. 150Always sends to the log. 151.It Fn aprint_naive 152Sends to the console only if 153.Dv AB_QUIET 154is set. 155Never sends to the log. 156.It Fn aprint_verbose 157Sends to the console only if 158.Dv AB_VERBOSE 159is set. 160Always sends to the log. 161.It Fn aprint_debug 162Sends to the console and the log only if 163.Dv AB_DEBUG 164is set. 165.It Fn aprint_error 166Like 167.Fn aprint_normal , 168but also keeps track of the number of times called. 169This allows a subsystem to report the number of errors that occurred 170during a quiet or silent initialization phase. 171.El 172.Pp 173For the 174.Fn aprint_* 175functions there are two additional families of functions with the 176suffixes 177.Dv _dev 178and 179.Dv _ifnet 180which work like their counterparts without the suffixes, except that 181they take a 182.Ft device_t 183or 184.Ft struct ifnet * 185respectively as first argument and prefix the log message with the 186corresponding device or interface name. 187.Pp 188The 189.Fn aprint_get_error_count 190function reports the number of errors and resets the counter to 0. 191.Pp 192If 193.Dv AB_SILENT 194is set, none of the autoconfiguration message printing routines send output 195to the console. 196The 197.Dv AB_VERBOSE 198and 199.Dv AB_DEBUG 200flags override 201.Dv AB_SILENT . 202.Sh RETURN VALUES 203The 204.Fn snprintf 205and 206.Fn vsnprintf 207functions return the number of characters placed in the buffer 208.Fa buf . 209This is different to the user-space functions of the same name. 210.Pp 211The 212.Fn tprintf_open 213function returns 214.Dv NULL 215if no terminal handle could be acquired. 216.Sh SEE ALSO 217.Xr printf 1 , 218.Xr printf 3 , 219.Xr bitmask_snprintf 9 220.Sh CODE REFERENCES 221.Pa sys/kern/subr_prf.c 222.Sh HISTORY 223The 224.Fn sprintf 225and 226.Fn vsprintf 227unsized string formatting functions are supported for compatibility only, 228and are not documented here. 229New code should use the size-limited 230.Fn snprintf 231and 232.Fn vsnprintf 233functions instead. 234.Pp 235In 236.Nx 1.5 237and earlier, 238.Fn printf 239supported more format strings than the user space 240.Fn printf . 241These nonstandard format strings are no longer supported. 242For the functionality provided by the former 243.Li %b 244format string, see 245.Xr bitmask_snprintf 9 . 246.Pp 247The 248.Fn aprint_normal , 249.Fn aprint_naive , 250.Fn aprint_verbose , 251and 252.Fn aprint_debug 253functions first appeared in 254.Bsx . 255.Sh BUGS 256The 257.Fn uprintf 258and 259.Fn ttyprintf 260functions should be used sparingly, if at all. 261Where multiple lines of output are required to reach a process's 262controlling terminal, 263.Fn tprintf 264is preferred. 265