1.\" $NetBSD: kprintf.9,v 1.19 2006/01/15 21:45:50 rillig Exp $ 2.\" 3.\" Copyright (c) 1998, 2002 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 January 15, 2006 38.Dt KPRINTF 9 39.Os 40.Sh NAME 41.Nm printf, snprintf, vprintf, vsnprintf, uprintf, ttyprintf, tprintf 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.Ft void 52.Fn "vprintf" "const char *format" "va_list ap" 53.Ft int 54.Fn "vsnprintf" "char *buf" "size_t size" "const char *format" "va_list ap" 55.Ft void 56.Fn "uprintf" "const char *format" "..." 57.Ft void 58.Fn "ttyprintf" "struct tty *tty" "const char *format" "..." 59.In sys/tprintf.h 60.Ft tpr_t 61.Fn "tprintf_open" "struct proc *p" 62.Ft void 63.Fn "tprintf" "tpr_t tpr" "const char *format" "..." 64.Ft void 65.Fn "tprintf_close" "tpr_t tpr" 66.Ft void 67.Fn "aprint_normal" "const char *format" "..." 68.Ft void 69.Fn "aprint_naive" "const char *format" "..." 70.Ft void 71.Fn "aprint_verbose" "const char *format" "..." 72.Ft void 73.Fn "aprint_debug" "const char *format" "..." 74.Ft void 75.Fn "aprint_error" "const char *format" "..." 76.Ft int 77.Fn "aprint_get_error_count" "void" 78.Sh DESCRIPTION 79The 80.Fn printf 81family of functions allows the kernel to send formatted messages to various 82output devices. 83The functions 84.Fn printf 85and 86.Fn vprintf 87send formatted strings to the system console. 88The 89.Fn printf_nolog 90function is identical to 91.Fn printf , 92except it does not send the data to the system log. 93The functions 94.Fn snprintf 95and 96.Fn vsnprintf 97write output to a string buffer. 98These four functions work similarly to their user space counterparts, 99and are not described in detail here. 100.Pp 101The functions 102.Fn uprintf 103and 104.Fn ttyprintf 105send formatted strings to the current process's controlling tty and a specific 106tty, respectively. 107.Pp 108The 109.Fn tprintf 110function sends formatted strings to a process's controlling tty, 111via a handle of type tpr_t. 112This allows multiple write operations to the tty with a guarantee that the 113tty will be valid across calls. 114A handle is acquired by calling 115.Fn tprintf_open 116with the target process as an argument. 117This handle must be closed with a matching call to 118.Fn tprintf_close . 119.Pp 120The functions 121.Fn aprint_normal , 122.Fn aprint_naive , 123.Fn aprint_verbose , 124.Fn aprint_debug , 125and 126.Fn aprint_error 127are intended to be used to print autoconfiguration messages, and change 128their behavior based on flags in the 129.Dq boothowto 130variable: 131.Bl -tag -width "aprint_verbose()" 132.It Fn aprint_normal 133Sends to the console unless 134.Dv AB_QUIET 135is set. 136Always sends to the log. 137.It Fn aprint_naive 138Sends to the console only if 139.Dv AB_QUIET 140is set. 141Never sends to the log. 142.It Fn aprint_verbose 143Sends to the console only if 144.Dv AB_VERBOSE 145is set. 146Always sends to the log. 147.It Fn aprint_debug 148Sends to the console and the log only if 149.Dv AB_DEBUG 150is set. 151.It Fn aprint_error 152Like 153.Fn aprint_normal , 154but also keeps track of the number of times called. 155This allows a subsystem to report the number of errors that occurred 156during a quiet or silent initialization phase. 157The 158.Fn aprint_get_error_count 159function reports the number of errors and resets the counter to 0. 160.El 161.Pp 162If 163.Dv AB_SILENT 164is set, none of the autoconfiguration message printing routines send output 165to the console. 166The 167.Dv AB_VERBOSE 168and 169.Dv AB_DEBUG 170flags override 171.Dv AB_SILENT . 172.Sh RETURN VALUES 173The 174.Fn snprintf 175and 176.Fn vsnprintf 177functions return the number of characters placed in the buffer 178.Fa buf . 179.Pp 180The 181.Fn tprintf_open 182function returns 183.Dv NULL 184if no terminal handle could be acquired. 185.Sh SEE ALSO 186.Xr printf 1 , 187.Xr printf 3 , 188.Xr bitmask_snprintf 9 189.Sh CODE REFERENCES 190.Pa sys/kern/subr_prf.c 191.Sh HISTORY 192The 193.Fn sprintf 194and 195.Fn vsprintf 196unsized string formatting functions are supported for compatibility only, 197and are not documented here. 198New code should use the size-limited 199.Fn snprintf 200and 201.Fn vsnprintf 202functions instead. 203.Pp 204In 205.Nx 1.5 206and earlier, 207.Fn printf 208supported more format strings than the user space 209.Fn printf . 210These nonstandard format strings are no longer supported. 211For the functionality provided by the former 212.Li %b 213format string, see 214.Xr bitmask_snprintf 9 . 215.Pp 216The 217.Fn aprint_normal , 218.Fn aprint_naive , 219.Fn aprint_verbose , 220and 221.Fn aprint_debug 222functions first appeared in 223.Bsx . 224.Sh BUGS 225The 226.Fn uprintf 227and 228.Fn ttyprintf 229functions should be used sparingly, if at all. 230Where multiple lines of output are required to reach a process's 231controlling terminal, 232.Fn tprintf 233is preferred. 234