1.\" $OpenBSD: printf.9,v 1.26 2022/09/11 06:38:11 jmc Exp $ 2.\" $NetBSD: kprintf.9,v 1.6 1999/03/16 00:40:47 garbled Exp $ 3.\" 4.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Jeremy Cooper. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: September 11 2022 $ 32.Dt PRINTF 9 33.Os 34.Sh NAME 35.Nm printf , 36.Nm snprintf , 37.Nm vprintf , 38.Nm vsnprintf , 39.Nm uprintf , 40.Nm ttyprintf , 41.Nm db_printf , 42.Nm db_vprintf 43.Nd kernel formatted output conversion 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/systm.h 47.Ft int 48.Fo printf 49.Fa "const char *format" 50.Fa "..." 51.Fc 52.Ft int 53.Fo snprintf 54.Fa "char *buf" 55.Fa "size_t size" 56.Fa "const char *format" 57.Fa "..." 58.Fc 59.Ft int 60.Fo vprintf 61.Fa "const char *format" 62.Fa "va_list ap" 63.Fc 64.Ft int 65.Fo vsnprintf 66.Fa "char *buf" 67.Fa "size_t size" 68.Fa "const char *fmt" 69.Fa "va_list ap" 70.Fc 71.Ft void 72.Fo uprintf 73.Fa "const char *format" 74.Fa "..." 75.Fc 76.Ft void 77.Fo ttyprintf 78.Fa "struct tty *tty" 79.Fa "const char *format" 80.Fa "..." 81.Fc 82.In ddb/db_output.h 83.Ft void 84.Fn db_printf "const char *format" ... 85.Ft void 86.Fn db_vprintf "const char *format" "va_list ap" 87.Sh DESCRIPTION 88The 89.Fn printf , 90.Fn snprintf , 91.Fn vprintf , 92.Fn vsnprintf , 93.Fn uprintf , 94.Fn ttyprintf , 95.Fn db_printf , 96and 97.Fn db_vprintf 98functions allow the kernel to send formatted messages to various output 99devices. 100The functions 101.Fn printf 102and 103.Fn vprintf 104send formatted strings to the system console and to the system log. 105The functions 106.Fn uprintf 107and 108.Fn ttyprintf 109send formatted strings to the current process's controlling tty and a specific 110tty, 111respectively. 112The functions 113.Fn db_printf 114and 115.Fn db_vprintf 116send formatted strings to the ddb console, and are only used to implement 117.Xr ddb 4 . 118.Pp 119Since each of these kernel functions is a variant of its user space 120counterpart, this page describes only the differences between the user 121space and kernel versions. 122.Pp 123Only a subset of the user space conversion specification is available to the 124kernel version: 125.Bd -filled -offset indent 126.Sm off 127.Cm % 128.Op Ar width 129.Op Ar size 130.Ar conversion 131.Sm on 132.Ed 133.Pp 134Refer to 135.Xr printf 3 136for functional details. 137.Ss FORMAT OPTIONS 138The kernel functions don't support as many formatting specifiers as their 139user space counterparts. 140In addition to the floating point formatting specifiers, 141the following integer type specifiers are not supported: 142.Bl -tag -width 5n 143.It Li %hh 144Argument of 145.Vt char 146type. 147This format specifier is accepted by the kernel but will be handled as 148.Li %h . 149.It Li %j 150Argument of 151.Vt intmax_t 152or 153.Vt uintmax_t 154type. 155.It Li %t 156Argument of 157.Vt ptrdiff_t 158type. 159.El 160.Pp 161The kernel functions support some additional formatting specifiers: 162.Bl -tag -width 5n 163.It Li %b 164Bit field expansion. 165This format specifier is useful for decoding bit fields in device registers. 166It displays an integer using a specified radix 167.Pq base 168and an interpretation of 169the bits within that integer as though they were flags. 170It requires two arguments from the argument vector, the first argument being 171the bit field to be decoded 172(of type 173.Vt int , 174unless a width modifier has been specified) 175and the second being a decoding directive string. 176.Pp 177The decoding directive string describes how the bitfield is to be interpreted 178and displayed. 179The first character of the string is a binary character representation of the 180output numeral base in which the bitfield will be printed before it is decoded. 181Recognized radix values 182.Pq "in C escape-character format" 183are 184.Li \e10 185.Pq octal , 186.Li \e12 187.Pq decimal , 188and 189.Li \e20 190.Pq hexadecimal . 191.Pp 192The remaining characters in the decoding directive string are interpreted as a 193list of bit-position\(endescription pairs. 194A bit-position\(endescription pair begins with a binary character value 195that represents the position of the bit being described. 196A bit position value of one describes the least significant bit. 197Whereas a position value of 32 198.Pq "octal 40, hexadecimal 20, the ASCII space character" 199describes the most significant bit. 200.Pp 201To deal with more than 32 bits, the characters 128 202.Pq "octal 200, hexadecimal 80" 203through 255 204.Pq "octal 377, hexadecimal FF" 205are used. 206The value 127 is subtracted from the character to determine the 207bit position (1 is least significant, and 128 is most significant). 208.Pp 209The remaining characters in a bit-position\(endescription pair are the 210characters to print should the bit being described be set. 211Description strings are delimited by the next bit position value character 212encountered 213.Po 214distinguishable by its value being \*(Le 32 or \*(Ge 128 215.Pc , 216or the end of the decoding directive string itself. 217.El 218.Sh RETURN VALUES 219The 220.Fn printf 221and 222.Fn vprintf 223functions return the number of characters printed. 224.Pp 225The 226.Fn snprintf 227and 228.Fn vsnprintf 229functions return the number of characters that would have been put into 230the buffer 231.Fa buf 232if the 233.Fa size 234were unlimited. 235.Sh EXAMPLES 236Use of the 237.Li %b 238format specifier for decoding device registers. 239.Bd -literal -offset indent 240printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 241\(rA "reg=3<BITTWO,BITONE>" 242 243printf("enablereg=%b\en", 0xe860, 244 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 245 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 246 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 247\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 248.Ed 249.Sh CODE REFERENCES 250.Pa sys/kern/subr_prf.c 251.Sh SEE ALSO 252.Xr revoke 2 , 253.Xr printf 3 , 254.Xr ddb 4 , 255.Xr log 9 256