1.\" $NetBSD: kprintf.9,v 1.22 2007/09/24 20:44:24 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 24, 2007 38.Dt KPRINTF 9 39.Os 40.Sh NAME 41.Nm printf, snprintf, vprintf, vsnprintf, uprintf, ttyprintf, tprintf, 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 autoconfiguration messages, and change 149their behavior based on flags in the 150.Dq boothowto 151variable: 152.Bl -tag -width "aprint_verbose()" 153.It Fn aprint_normal 154Sends to the console unless 155.Dv AB_QUIET 156is set. 157Always sends to the log. 158.It Fn aprint_naive 159Sends to the console only if 160.Dv AB_QUIET 161is set. 162Never sends to the log. 163.It Fn aprint_verbose 164Sends to the console only if 165.Dv AB_VERBOSE 166is set. 167Always sends to the log. 168.It Fn aprint_debug 169Sends to the console and the log only if 170.Dv AB_DEBUG 171is set. 172.It Fn aprint_error 173Like 174.Fn aprint_normal , 175but also keeps track of the number of times called. 176This allows a subsystem to report the number of errors that occurred 177during a quiet or silent initialization phase. 178.El 179.Pp 180For the 181.Fn aprint_* 182functions there are two additional families of functions with the 183suffixes 184.Dv _dev 185and 186.Dv _ifnet 187which work like their counterparts without the suffixes, except that 188they take a 189.Ft device_t 190or 191.Ft struct ifnet * 192respectively as first argument and prefix the log message with the 193corresponding device or interface name. 194.Pp 195The 196.Fn aprint_get_error_count 197function reports the number of errors and resets the counter to 0. 198.Pp 199If 200.Dv AB_SILENT 201is set, none of the autoconfiguration message printing routines send output 202to the console. 203The 204.Dv AB_VERBOSE 205and 206.Dv AB_DEBUG 207flags override 208.Dv AB_SILENT . 209.Sh RETURN VALUES 210The 211.Fn snprintf 212and 213.Fn vsnprintf 214functions return the number of characters placed in the buffer 215.Fa buf . 216This is different to the user-space functions of the same name. 217.Pp 218The 219.Fn tprintf_open 220function returns 221.Dv NULL 222if no terminal handle could be acquired. 223.Sh SEE ALSO 224.Xr printf 1 , 225.Xr printf 3 , 226.Xr bitmask_snprintf 9 227.Sh CODE REFERENCES 228.Pa sys/kern/subr_prf.c 229.Sh HISTORY 230The 231.Fn sprintf 232and 233.Fn vsprintf 234unsized string formatting functions are supported for compatibility only, 235and are not documented here. 236New code should use the size-limited 237.Fn snprintf 238and 239.Fn vsnprintf 240functions instead. 241.Pp 242In 243.Nx 1.5 244and earlier, 245.Fn printf 246supported more format strings than the user space 247.Fn printf . 248These nonstandard format strings are no longer supported. 249For the functionality provided by the former 250.Li %b 251format string, see 252.Xr bitmask_snprintf 9 . 253.Pp 254The 255.Fn aprint_normal , 256.Fn aprint_naive , 257.Fn aprint_verbose , 258and 259.Fn aprint_debug 260functions first appeared in 261.Bsx . 262.Sh BUGS 263The 264.Fn uprintf 265and 266.Fn ttyprintf 267functions should be used sparingly, if at all. 268Where multiple lines of output are required to reach a process's 269controlling terminal, 270.Fn tprintf 271is preferred. 272