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