1.\" $OpenBSD: printf.9,v 1.18 2011/09/19 10:25:37 miod 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: September 19 2011 $ 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 as many formatting specifiers as their 120user space counterparts. 121In addition to the floating point formatting specifiers, 122the following integer type specifiers are not supported in the format string 123.Fa format 124either : 125.Bl -tag -width 5n 126.It Li %hh 127Argument of 128.Li char 129type. 130This format specifier is accepted by the kernel but will be handled as 131.Li %h . 132.It Li %j 133Argument of 134.Li intmax_t 135or 136.Li uintmax_t 137type. 138.It Li %t 139Argument of 140.Li ptrdiff_t 141type. 142.El 143.Pp 144The kernel functions also accept the following format specifiers 145in the format string 146.Fa format : 147.Bl -tag -width 5n 148.It Li %b 149Bit field expansion. 150This format specifier is useful for decoding bit fields in device registers. 151It displays an integer using a specified radix 152.Pq base 153and an interpretation of 154the bits within that integer as though they were flags. 155It requires two arguments from the argument vector, the first argument being 156the bit field to be decoded 157(of type 158.Li int , 159unless a width modifier has been specified) 160and the second being a decoding directive string. 161.Pp 162The decoding directive string describes how the bitfield is to be interpreted 163and displayed. 164The first character of the string is a binary character representation of the 165output numeral base in which the bitfield will be printed before it is decoded. 166Recognized radix values 167.Pq "in C escape-character format" 168are 169.Li \e10 170.Pq octal , 171.Li \e12 172.Pq decimal , 173and 174.Li \e20 175.Pq hexadecimal . 176.Pp 177The remaining characters in the decoding directive string are interpreted as a 178list of bit-position\(endescription pairs. 179A bit-position\(endescription pair begins with a binary character value 180that represents the position of the bit being described. 181A bit position value of one describes the least significant bit. 182Whereas a position value of 32 183.Pq "octal 40, hexadecimal 20, the ASCII space character" 184describes the most significant bit. 185.Pp 186To deal with more than 32 bits, the characters 128 187.Pq "octal 200, hexadecimal 80" 188through 255 189.Pq "octal 377, hexadecimal FF" 190are used. 191The value 127 is subtracted from the character to determine the 192bit position (1 is least significant, and 128 is most significant). 193.Pp 194The remaining characters in a bit-position\(endescription pair are the 195characters to print should the bit being described be set. 196Description strings are delimited by the next bit position value character 197encountered 198.Po 199distinguishable by its value being \*(Le 32 or \*(Ge 128 200.Pc , 201or the end of the decoding directive string itself. 202.El 203.Sh RETURN VALUES 204The 205.Fn printf 206and 207.Fn vprintf 208functions return the number of characters printed. 209.Pp 210The 211.Fn snprintf 212and 213.Fn vsnprintf 214functions return the number of characters that would have been put into 215the buffer 216.Fa buf 217if the 218.Fa size 219were unlimited. 220.Sh EXAMPLES 221Use of the 222.Li %b 223format specifier for decoding device registers. 224.Bd -literal -offset indent 225printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") 226\(rA "reg=3<BITTWO,BITONE>" 227 228printf("enablereg=%b\en", 0xe860, 229 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 230 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 231 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 232\(rA "enablereg=e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 233.Ed 234.Sh CODE REFERENCES 235.Pa sys/kern/subr_prf.c 236.Sh SEE ALSO 237.Xr revoke 2 , 238.Xr printf 3 , 239.Xr ddb 4 , 240.Xr log 9 241