1.\" $NetBSD: kprintf.9,v 1.5 1998/09/10 04:04:42 enami 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 Sep 1, 1998 38.Dt KPRINTF 9 39.Os NetBSD 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. 161.It Li %r 162Integer value using current 163.Tn DDB 164radix. 165.Bf -emphasis 166This format specifier is only availble in kernels enabled with the 167.Tn DDB 168debugger. 169.Po 170See 171.Xr ddb 4 172.Pc . 173.Ef 174Displays an integer using the current 175.Tn DDB 176radix. 177.It Li %z 178Signed hexadecimal with 179.Ql 0x 180prefix. 181.Bf -emphasis 182This format specifier is only available in kernels enabled with the 183.Tn DDB 184debugger. 185.Po 186See 187.Xr ddb 4 188.Pc . 189.Ef 190Displays a signed integer using the C-style hexadecimal constant format. 191.El 192.Sh RETURN VALUES 193The 194.Fn sprintf 195function returns the number of characters it placed in the buffer 196.Fa buf . 197.Sh EXAMPLES 198An example use of the 199.Li %b 200format specifier for decoding device registers. 201.Bd -literal -offset indent 202printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 203\(rA "reg=3<BITTWO,BITONE>" 204 205printf("enablereg=%b\en", 0xe860, 206 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 207 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 208 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 209\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 210.Ed 211.Pp 212An example use of the 213.Li %: 214format specifier for recursive formatting. 215.Bd -literal -offset indent 216void 217bail(char *fmt, ...) 218{ 219 va_list ap; 220 va_start (ap, fmt); 221 printf("bailing out: %:\en", fmt, ap); 222 va_end(ap); 223} 224 225bail("descriptor %d is invalid.", 5) 226\(rA "bailing out: descriptor 5 is invalid" 227.Ed 228.Sh SEE ALSO 229.\" The following page has not been written, but I am including a cross- 230.\" reference to it in the hopes that it will inspire someone to write it. 231.Xr printf 3 , 232.Xr printf 1 , 233.Xr ddb 4 , 234.Xr tprintf 9 235.Sh CODE REFERENCES 236.Pa sys/kern/subr_prf.c 237.Sh BUGS 238The 239.Li %b 240format specifier cannot be used to decode integers greater than 32 bits in 241size. 242The 243.Fn uprintf 244and 245.Fn ttyprintf 246functions should be used sparingly, if at all. 247