1.\" $OpenBSD: printf.9,v 1.13 2007/01/26 00:20:47 jason 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.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd September 1, 1998 39.Dt PRINTF 9 40.Os 41.Sh NAME 42.Nm printf , 43.Nm snprintf , 44.Nm vprintf , 45.Nm vsnprintf , 46.Nm uprintf , 47.Nm ttyprintf , 48.Nm db_printf 49.Nd kernel formatted output conversion 50.Sh SYNOPSIS 51.Fd #include <sys/types.h> 52.Fd #include <sys/systm.h> 53.Ft int 54.Fo "printf" 55.Fa "const char *format" 56.Fa "..." 57.Fc 58.Ft int 59.Fo "snprintf" 60.Fa "char *buf" 61.Fa "size_t size" 62.Fa "const char *format" 63.Fa "..." 64.Fc 65.Ft int 66.Fo "vprintf" 67.Fa "const char *format" 68.Fa "va_list ap" 69.Fc 70.Ft int 71.Fo "vsnprintf" 72.Fa "char *buf" 73.Fa "size_t size" 74.Fa "const char *fmt" 75.Fa "va_list ap" 76.Fc 77.Ft void 78.Fo "uprintf" 79.Fa "const char *format" 80.Fa "..." 81.Fc 82.Ft void 83.Fo "ttyprintf" 84.Fa "struct tty *tty" 85.Fa "const char *format" 86.Fa "..." 87.Fc 88.Ft void 89.Fn db_printf "const char *format" ... 90.Sh DESCRIPTION 91The 92.Fn printf , 93.Fn snprintf , 94.Fn vprintf , 95.Fn vsnprintf , 96.Fn uprintf , 97.Fn ttyprintf , 98and 99.Fn db_printf 100functions allow the kernel to send formatted messages to various output 101devices. 102The functions 103.Fn printf 104and 105.Fn vprintf 106send formatted strings to the system console and to the system log. 107The functions 108.Fn uprintf 109and 110.Fn ttyprintf 111send formatted strings to the current process's controlling tty and a specific 112tty, 113respectively. 114The function 115.Fn db_printf 116sends formatted strings to the ddb console, and is 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 any floating point formatting 127specifiers. 128In addition to other formatting specifiers common with the user 129space functions, the kernel functions accept the following format specifiers 130in the format string 131.Fa format : 132.Bl -tag -width "\e177" 133.It Li %b 134Bit field expansion. 135This format specifier is useful for decoding bit fields in device registers. 136It displays an integer using a specified radix 137.Pq base 138and an interpretation of 139the bits within that integer as though they were flags. 140It requires two arguments from the argument vector, the first argument being 141the bit field to be decoded 142.Pq "as an integer" 143and the second being a decoding directive string. 144.Pp 145The decoding directive string describes how the bitfield is to be interpreted 146and displayed. 147The first character of the string is a binary character representation of the 148output numeral base in which the bitfield will be printed before it is decoded. 149Recognized radix values 150.Pq "in C escape-character format" 151are 152.Li \e10 153.Pq octal , 154.Li \e12 155.Pq decimal , 156and 157.Li \e20 158.Pq hexadecimal . 159.Pp 160The remaining characters in the decoding directive string are interpreted as a 161list of bit-position\(endescription pairs. 162A bit-position\(endescription pair begins with a binary character value 163that represents the position of the bit being described. 164A bit position value of one describes the least significant bit. 165Whereas a position value of 32 166.Pq "octal 40, hexadecimal 20, the ASCII space character" 167describes the most significant bit. 168.Pp 169To deal with more than 32 bits, the characters 128 170.Pq "octal 200, hexadecimal 80" 171through 255 172.Pq "octal 377, hexadecimal FF" 173are used. 174The value 127 is subtracted from the character to determine the 175bit position (1 is least significant, and 128 is most significant). 176.Pp 177The remaining characters in a bit-position\(endescription pair are the 178characters to print should the bit being described be set. 179Description strings are delimited by the next bit position value character 180encountered 181.Po 182distinguishable by its value being \*(Le 32 or \*(Ge 128 183.Pc , 184or the end of the decoding directive string itself. 185.It Li %r 186Displays an integer using the current 187.Tn DDB 188radix. 189This non-standard interpretation of 190.Li %r 191is only available to 192.Fn db_printf . 193.It Li %z 194Displays a signed integer using the C-style hexadecimal constant format. 195This format specifier is only available to 196.Fn db_printf . 197.El 198.Sh RETURN VALUES 199The 200.Fn printf , 201.Fn snprintf , 202.Fn vprintf , 203and 204.Fn vsnprintf 205functions return the number of characters they placed in the buffer 206.Fa buf . 207.Sh EXAMPLES 208Use of the 209.Li %b 210format specifier for decoding device registers. 211.Bd -literal -offset indent 212printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 213\(rA "reg=3<BITTWO,BITONE>" 214 215printf("enablereg=%b\en", 0xe860, 216 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 217 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 218 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 219\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 220.Ed 221.Sh SEE ALSO 222.Xr revoke 2 , 223.Xr printf 3 , 224.Xr ddb 4 , 225.Xr log 9 226.Sh CODE REFERENCES 227.Pa sys/kern/subr_prf.c 228