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