1.\" $NetBSD: kprintf.9,v 1.8 2000/02/07 12:37:02 abs Exp $ 2.\" 3.\" Copyright (c) 1998 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. 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 1, 1998 38.Dt KPRINTF 9 39.Os 40.Sh NAME 41.Nm printf, sprintf, vprintf, uprintf, ttyprintf 42.Nd kernel formatted output conversion 43.Sh SYNOPSIS 44.Fd #include <sys/systm.h> 45.Ft void 46.Fo "printf" 47.Fa "const char *format" 48.Fa "..." 49.Fc 50.Ft int 51.Fo "sprintf" 52.Fa "char *buf" 53.Fa "const char *format" 54.Fa "..." 55.Fc 56.Ft void 57.Fo "vprintf" 58.Fa "const char *format" 59.Fa "va_list ap" 60.Fc 61.Ft void 62.Fo "uprintf" 63.Fa "const char *format" 64.Fa "..." 65.Fc 66.Ft void 67.Fo "ttyprintf" 68.Fa "struct tty *tty" 69.Fa "const char *format" 70.Fa "..." 71.Fc 72.Sh DESCRIPTION 73The 74.Fn printf , 75.Fn sprintf , 76.Fn vprintf , 77.Fn uprintf , 78and 79.Fn ttyprintf 80functions allow the kernel to send formatted messages to various output 81devices. 82The functions 83.Fn printf 84and 85.Fn vprintf 86send formatted strings to the system console. 87The functions 88.Fn uprintf 89and 90.Fn ttyprintf 91send formatted strings to the current process's controlling tty and a specific 92tty, 93respectively. 94.Pp 95Since each of these kernel functions is a scaled down version of its user space 96counterpart 97.Po 98.Xr printf 3 , 99.Xr sprintf 3 , 100and 101.Xr vprintf 3 102.Pc , 103this page describes only the differences between the user space and kernel 104versions, rather than describing all of their functional details. 105.Ss FORMAT OPTIONS 106In addition to the formatting specifiers that the user space functions 107accept in the format string 108.Fa format , 109the kernel functions accept the following format specifiers. 110.Pp 111.Bl -tag -width "\e177" 112.It Li %b 113Bit field expansion. 114This format specifier is useful for decoding bit fields in device registers. 115It displays an integer using a specified radix 116.Pq base 117and an interpretation of 118the bits within that integer as though they were flags. 119It requires two arguments from the argument vector, the first argument being 120the bit field to be decoded 121.Pq "as an integer" 122and the second being a decoding directive string. 123.Pp 124The decoding directive string describes how the bitfield is to be interpreted 125and displayed. 126The first character of the string is a binary character representation of the 127output numeral base in which the bitfield will be printed before it is decoded. 128Recognized radix values 129.Pq "in C escape-character format" 130are 131.Li \e10 132.Pq octal , 133.Li \e12 134.Pq decimal , 135and 136.Li \e20 137.Pq hexadecimal . 138.Pp 139The remaining characters in the decoding directive string are interpreted as a 140list of bit-position\(endescription pairs. 141A bit-position\(endescription pair begins with a binary character value 142that represents the position of the bit being described. 143A bit position value of one describes the least significant bit. 144Whereas a position value of 32 145.Pq "octal 40, hexadecimal 20, the ASCII space character" 146describes the most significant bit. 147.Pp 148The remaining characters in a bit-position\(endescription pair are the 149characters to print should the bit being described be set. 150Description strings are delimited by the next bit position value character 151encountered 152.Pq "distinguishable by its value being \(<= 32" , 153or the end of the decoding directive string itself. 154.It Li %: 155Inline format continuation. 156This format specifier allows for recursive formatted output. 157Its argument is the new formatting string to obey and the argument which 158follows it is a 159.Va va_list 160argument vector from which to obtain the data to be formatted. 161The 162.Li %: 163specifier is non portable, and its use is strongly discouraged, even in 164NetBSD specific code (it is not supported on all ports). 165.It Li %r 166Integer value using current 167.Tn DDB 168radix. 169.Bf -emphasis 170This format specifier is only availble in kernels enabled with the 171.Tn DDB 172debugger. 173.Po 174See 175.Xr ddb 4 176.Pc . 177.Ef 178Displays an integer using the current 179.Tn DDB 180radix. 181.It Li %z 182Signed hexadecimal with 183.Ql 0x 184prefix. 185.Bf -emphasis 186This format specifier is only available in kernels enabled with the 187.Tn DDB 188debugger. 189.Po 190See 191.Xr ddb 4 192.Pc . 193.Ef 194Displays a signed integer using the C-style hexadecimal constant format. 195.El 196.Sh RETURN VALUES 197The 198.Fn sprintf 199function returns the number of characters it placed in the buffer 200.Fa buf . 201.Sh EXAMPLES 202An example use of the 203.Li %b 204format specifier for decoding device registers. 205.Bd -literal -offset indent 206printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 207\(rA "reg=3<BITTWO,BITONE>" 208 209printf("enablereg=%b\en", 0xe860, 210 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 211 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 212 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 213\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 214.Ed 215.Pp 216An example use of the 217.Li %: 218format specifier for recursive formatting. 219.Bd -literal -offset indent 220void 221bail(char *fmt, ...) 222{ 223 va_list ap; 224 va_start (ap, fmt); 225 printf("bailing out: %:\en", fmt, ap); 226 va_end(ap); 227} 228 229bail("descriptor %d is invalid.", 5) 230\(rA "bailing out: descriptor 5 is invalid" 231.Ed 232.Sh SEE ALSO 233.\" The following page has not been written, but I am including a cross- 234.\" reference to it in the hopes that it will inspire someone to write it. 235.Xr printf 3 , 236.Xr printf 1 , 237.Xr ddb 4 , 238.Xr tprintf 9 239.Sh CODE REFERENCES 240.Pa sys/kern/subr_prf.c 241.Sh BUGS 242The 243.Li %b 244format specifier cannot be used to decode integers greater than 32 bits in 245size. 246The 247.Fn uprintf 248and 249.Fn ttyprintf 250functions should be used sparingly, if at all. 251