1.\" $OpenBSD: printf.9,v 1.10 2003/06/13 01:14:54 tedu 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.Pp 133.Bl -tag -width "\e177" 134.It Li %b 135Bit field expansion. 136This format specifier is useful for decoding bit fields in device registers. 137It displays an integer using a specified radix 138.Pq base 139and an interpretation of 140the bits within that integer as though they were flags. 141It requires two arguments from the argument vector, the first argument being 142the bit field to be decoded 143.Pq "as an integer" 144and the second being a decoding directive string. 145.Pp 146The decoding directive string describes how the bitfield is to be interpreted 147and displayed. 148The first character of the string is a binary character representation of the 149output numeral base in which the bitfield will be printed before it is decoded. 150Recognized radix values 151.Pq "in C escape-character format" 152are 153.Li \e10 154.Pq octal , 155.Li \e12 156.Pq decimal , 157and 158.Li \e20 159.Pq hexadecimal . 160.Pp 161The remaining characters in the decoding directive string are interpreted as a 162list of bit-position\(endescription pairs. 163A bit-position\(endescription pair begins with a binary character value 164that represents the position of the bit being described. 165A bit position value of one describes the least significant bit. 166Whereas a position value of 32 167.Pq "octal 40, hexadecimal 20, the ASCII space character" 168describes the most significant bit. 169.Pp 170The remaining characters in a bit-position\(endescription pair are the 171characters to print should the bit being described be set. 172Description strings are delimited by the next bit position value character 173encountered 174.Pq "distinguishable by its value being \(<= 32" , 175or the end of the decoding directive string itself. 176.It Li %: 177Inline format continuation. 178This format specifier allows for recursive formatted output. 179Its argument is the new formatting string to obey and the argument which 180follows it is a 181.Va va_list 182argument vector from which to obtain the data to be formatted. 183.It Li %r 184Displays an integer using the current 185.Tn DDB 186radix. 187This non-standard interpretation of 188.Li %r 189is only available to 190.Fn db_printf . 191.It Li %z 192Displays a signed integer using the C-style hexadecimal constant format. 193This format specifier is only available to 194.Fn db_printf . 195.El 196.Sh RETURN VALUES 197The 198.Fn printf , 199.Fn snprintf , 200.Fn vprintf , 201and 202.Fn vsnprintf 203functions return the number of characters they placed in the buffer 204.Fa buf . 205.Sh EXAMPLES 206Use of the 207.Li %b 208format specifier for decoding device registers. 209.Bd -literal -offset indent 210printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 211\(rA "reg=3<BITTWO,BITONE>" 212 213printf("enablereg=%b\en", 0xe860, 214 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 215 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 216 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 217\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 218.Ed 219.Pp 220Use of the 221.Li %: 222format specifier for recursive formatting. 223.Bd -literal -offset indent 224void 225bail(char *fmt, ...) 226{ 227 va_list ap; 228 va_start (ap, fmt); 229 printf("bailing out: %:\en", fmt, ap); 230 va_end(ap); 231} 232 233bail("descriptor %d is invalid.", 5) 234\(rA "bailing out: descriptor 5 is invalid" 235.Ed 236.Sh SEE ALSO 237.Xr revoke 2 , 238.Xr printf 3 , 239.Xr ddb 4 , 240.Xr log 9 241.Sh CODE REFERENCES 242.Pa sys/kern/subr_prf.c 243.Sh LIMITATIONS 244The 245.Li %b 246format specifier cannot be used to decode integers greater than 32 bits in 247size. 248