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