1.\" $OpenBSD: printf.9,v 1.24 2015/11/07 03:48:25 mmcc 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: November 7 2015 $ 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. 122Refer to 123.Xr printf 3 124for functional details. 125.Ss FORMAT OPTIONS 126The kernel functions don't support as many formatting specifiers as their 127user space counterparts. 128In addition to the floating point formatting specifiers, 129the following integer type specifiers are not supported: 130.Bl -tag -width 5n 131.It Li %hh 132Argument of 133.Li char 134type. 135This format specifier is accepted by the kernel but will be handled as 136.Li %h . 137.It Li %j 138Argument of 139.Li intmax_t 140or 141.Li uintmax_t 142type. 143.It Li %t 144Argument of 145.Li ptrdiff_t 146type. 147.El 148.Pp 149The kernel functions support some additional formatting specifiers: 150.Bl -tag -width 5n 151.It Li %b 152Bit field expansion. 153This format specifier is useful for decoding bit fields in device registers. 154It displays an integer using a specified radix 155.Pq base 156and an interpretation of 157the bits within that integer as though they were flags. 158It requires two arguments from the argument vector, the first argument being 159the bit field to be decoded 160(of type 161.Li int , 162unless a width modifier has been specified) 163and the second being a decoding directive string. 164.Pp 165The decoding directive string describes how the bitfield is to be interpreted 166and displayed. 167The first character of the string is a binary character representation of the 168output numeral base in which the bitfield will be printed before it is decoded. 169Recognized radix values 170.Pq "in C escape-character format" 171are 172.Li \e10 173.Pq octal , 174.Li \e12 175.Pq decimal , 176and 177.Li \e20 178.Pq hexadecimal . 179.Pp 180The remaining characters in the decoding directive string are interpreted as a 181list of bit-position\(endescription pairs. 182A bit-position\(endescription pair begins with a binary character value 183that represents the position of the bit being described. 184A bit position value of one describes the least significant bit. 185Whereas a position value of 32 186.Pq "octal 40, hexadecimal 20, the ASCII space character" 187describes the most significant bit. 188.Pp 189To deal with more than 32 bits, the characters 128 190.Pq "octal 200, hexadecimal 80" 191through 255 192.Pq "octal 377, hexadecimal FF" 193are used. 194The value 127 is subtracted from the character to determine the 195bit position (1 is least significant, and 128 is most significant). 196.Pp 197The remaining characters in a bit-position\(endescription pair are the 198characters to print should the bit being described be set. 199Description strings are delimited by the next bit position value character 200encountered 201.Po 202distinguishable by its value being \*(Le 32 or \*(Ge 128 203.Pc , 204or the end of the decoding directive string itself. 205.El 206.Sh RETURN VALUES 207The 208.Fn printf 209and 210.Fn vprintf 211functions return the number of characters printed. 212.Pp 213The 214.Fn snprintf 215and 216.Fn vsnprintf 217functions return the number of characters that would have been put into 218the buffer 219.Fa buf 220if the 221.Fa size 222were unlimited. 223.Sh EXAMPLES 224Use of the 225.Li %b 226format specifier for decoding device registers. 227.Bd -literal -offset indent 228printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 229\(rA "reg=3<BITTWO,BITONE>" 230 231printf("enablereg=%b\en", 0xe860, 232 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 233 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 234 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 235\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 236.Ed 237.Sh CODE REFERENCES 238.Pa sys/kern/subr_prf.c 239.Sh SEE ALSO 240.Xr revoke 2 , 241.Xr printf 3 , 242.Xr ddb 4 , 243.Xr log 9 244