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