1.\" $OpenBSD: printf.9,v 1.6 2001/07/31 19:55:44 deraadt 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 Sep 1, 1998 39.Dt PRINTF 9 40.Os 41.Sh NAME 42.Nm printf , 43.Nm sprintf , 44.Nm vprintf , 45.Nm uprintf , 46.Nm ttyprintf , 47.Nm db_printf 48.Nd kernel formatted output conversion 49.Sh SYNOPSIS 50.Fd #include <sys/types.h> 51.Fd #include <sys/systm.h> 52.Ft void 53.Fo "printf" 54.Fa "const char *format" 55.Fa "..." 56.Fc 57.Ft int 58.Fo "sprintf" 59.Fa "char *buf" 60.Fa "const char *format" 61.Fa "..." 62.Fc 63.Ft void 64.Fo "vprintf" 65.Fa "const char *format" 66.Fa "va_list ap" 67.Fc 68.Ft void 69.Fo "uprintf" 70.Fa "const char *format" 71.Fa "..." 72.Fc 73.Ft void 74.Fo "ttyprintf" 75.Fa "struct tty *tty" 76.Fa "const char *format" 77.Fa "..." 78.Fc 79.Ft void 80.Fn db_printf "const char *format" ... 81.Sh DESCRIPTION 82The 83.Fn printf , 84.Fn sprintf , 85.Fn vprintf , 86.Fn uprintf , 87.Fn ttyprintf , 88and 89.Fn db_printf 90functions allow the kernel to send formatted messages to various output 91devices. 92The functions 93.Fn printf 94and 95.Fn vprintf 96send formatted strings to the system console and to the system log. 97The functions 98.Fn uprintf 99and 100.Fn ttyprintf 101send formatted strings to the current process's controlling tty and a specific 102tty, 103respectively. 104The function 105.Fn db_printf 106sends formatted strings to the ddb console, and is only used to implement 107.Xr ddb 4 . 108.Pp 109Since each of these kernel functions is a variant of its user space 110counterpart, this page describes only the differences between the user 111space and kernel versions. 112Refer to 113.Xr printf 3 114for functional details. 115.Ss FORMAT OPTIONS 116The kernel functions don't support any floating point formatting 117specifiers. 118In addition to other formatting specifiers common with the user 119space functions, the kernel functions accept the following format specifiers 120in the format string 121.Fa format : 122.Pp 123.Bl -tag -width "\e177" 124.It Li %b 125Bit field expansion. 126This format specifier is useful for decoding bit fields in device registers. 127It displays an integer using a specified radix 128.Pq base 129and an interpretation of 130the bits within that integer as though they were flags. 131It requires two arguments from the argument vector, the first argument being 132the bit field to be decoded 133.Pq "as an integer" 134and the second being a decoding directive string. 135.Pp 136The decoding directive string describes how the bitfield is to be interpreted 137and displayed. 138The first character of the string is a binary character representation of the 139output numeral base in which the bitfield will be printed before it is decoded. 140Recognized radix values 141.Pq "in C escape-character format" 142are 143.Li \e10 144.Pq octal , 145.Li \e12 146.Pq decimal , 147and 148.Li \e20 149.Pq hexadecimal . 150.Pp 151The remaining characters in the decoding directive string are interpreted as a 152list of bit-position\(endescription pairs. 153A bit-position\(endescription pair begins with a binary character value 154that represents the position of the bit being described. 155A bit position value of one describes the least significant bit. 156Whereas a position value of 32 157.Pq "octal 40, hexadecimal 20, the ASCII space character" 158describes the most significant bit. 159.Pp 160The remaining characters in a bit-position\(endescription pair are the 161characters to print should the bit being described be set. 162Description strings are delimited by the next bit position value character 163encountered 164.Pq "distinguishable by its value being \(<= 32" , 165or the end of the decoding directive string itself. 166.It Li %: 167Inline format continuation. 168This format specifier allows for recursive formatted output. 169Its argument is the new formatting string to obey and the argument which 170follows it is a 171.Va va_list 172argument vector from which to obtain the data to be formatted. 173.It Li %r 174Displays an integer using the current 175.Tn DDB 176radix. 177This non-standard interpretation of 178.Li %r 179is only available to 180.Fn db_printf . 181.It Li %z 182Displays a signed integer using the C-style hexadecimal constant format. 183This format specifier is only available to 184.Fn db_printf . 185.El 186.Sh RETURN VALUES 187The 188.Fn sprintf 189function returns the number of characters it placed in the buffer 190.Fa buf . 191.Sh EXAMPLES 192Use of the 193.Li %b 194format specifier for decoding device registers. 195.Bd -literal -offset indent 196printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 197\(rA "reg=3<BITTWO,BITONE>" 198 199printf("enablereg=%b\en", 0xe860, 200 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 201 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 202 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 203\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 204.Ed 205.Pp 206Use of the 207.Li %: 208format specifier for recursive formatting. 209.Bd -literal -offset indent 210void 211bail(char *fmt, ...) 212{ 213 va_list ap; 214 va_start (ap, fmt); 215 printf("bailing out: %:\en", fmt, ap); 216 va_end(ap); 217} 218 219bail("descriptor %d is invalid.", 5) 220\(rA "bailing out: descriptor 5 is invalid" 221.Ed 222.Sh SEE ALSO 223.\" The following page has not been written, but I am including a cross- 224.\" reference to it in the hopes that it will inspire someone to write it. 225.Xr revoke 2 , 226.Xr printf 3 , 227.Xr ddb 4 , 228.Xr log 9 229.Sh CODE REFERENCES 230.Pa sys/kern/subr_prf.c 231.Sh LIMITATIONS 232The 233.Li %b 234format specifier cannot be used to decode integers greater than 32 bits in 235size. 236