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