1.\" 2.\" Copyright (c) 2001 Andrew R. Reiter 3.\" Copyright (c) 2004 Joerg Wunsch 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/share/man/man9/printf.9,v 1.8 2006/09/08 14:05:03 ru Exp $ 28.\" $DragonFly: src/share/man/man9/kprintf.9,v 1.2 2007/04/09 21:20:37 swildner Exp $ 29.\" 30.Dd January 1, 2007 31.Dt KPRINTF 9 32.Os 33.Sh NAME 34.Nm kprintf , 35.Nm ksprintf , 36.Nm ksnprintf , 37.Nm kvprintf , 38.Nm kvsprintf , 39.Nm kvsnprintf , 40.Nm tprintf , 41.Nm uprintf , 42.Nm log 43.Nd formatted output conversion 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/systm.h 47.Ft int 48.Fn kprintf "const char *format" ... 49.Ft int 50.Fn ksprintf "char *str" "const char *format" ... 51.Ft int 52.Fn ksnprintf "char *str" "size_t size" "const char *format" ... 53.Ft int 54.Fn kvprintf "const char *format" "__va_list ap" 55.Ft int 56.Fn kvsprintf "char *str" "const char *format" "__va_list ap" 57.Ft int 58.Fn kvsnprintf "char *str" "size_t size" "const char *format" "__va_list ap" 59.Ft void 60.Fn tprintf "struct proc *p" "int pri" "const char *format" ... 61.Ft int 62.Fn uprintf "const char *format" ... 63.In sys/syslog.h 64.Ft void 65.Fn log "int pri" "const char *format" ... 66.Sh DESCRIPTION 67The 68.Nm 69family of functions are similar to the 70.Xr printf 3 71family of functions. 72The different functions each use a different output stream. 73The 74.Fn uprintf 75function outputs to the current process' controlling tty, while 76.Fn kprintf , 77.Fn ksprintf , 78.Fn ksnprintf , 79.Fn kvprintf , 80.Fn kvsprintf 81and 82.Fn kvsnprintf 83write to the console as well as to the logging facility. 84The 85.Fn tprintf 86function outputs to the tty associated with the process 87.Fa p 88and the logging facility if 89.Fa pri 90is not \-1. 91The 92.Fn log 93function sends the message to the kernel logging facility, using 94the log level as indicated by 95.Fa pri . 96.Pp 97Each of these related functions use the 98.Fa format , 99.Fa str , 100.Fa size 101and 102.Fa va 103parameters in the same manner as 104.Xr printf 3 . 105However, the 106.Nm 107functions add two other conversion specifiers to 108.Fa format : 109.Pp 110The 111.Cm \&%b 112identifier expects two arguments: an 113.Vt int 114and a 115.Vt "char *" . 116These are used as a register value and a print mask for decoding bitmasks. 117The print mask is made up of two parts: the base and the 118arguments. 119The base value is the output base expressed as an integer value; 120for example, \e10 gives octal and \e20 gives hexadecimal. 121The arguments are made up of a sequence of bit identifiers. 122Each bit identifier begins with an integer value which is the number of the 123bit (starting from 1) this identifier describes. 124The rest of the identifier is a string of characters containing the name of 125the bit. 126The string is terminated by either the bit number at the start of the next 127bit identifier or 128.Dv NUL 129for the last bit identifier. 130.Pp 131The 132.Cm \&%D 133identifier is meant to assist in hexdumps. 134It requires two arguments: a 135.Vt "u_char *" 136pointer and a 137.Vt "char *" 138string. 139The memory pointed to be the pointer is output in hexadecimal one byte at 140a time. 141The string is used as a delimiter between individual bytes. 142If present, a width directive will specify the number of bytes to display. 143By default, 16 bytes of data are output. 144.Pp 145The 146.Fn log 147function uses 148.Xr syslog 3 149level values 150.Dv LOG_DEBUG 151through 152.Dv LOG_EMERG 153for its 154.Fa pri 155parameter (mistakenly called 156.Sq priority 157here). 158Alternatively, if a 159.Fa pri 160of \-1 is given, the message will be appended to the last log message 161started by a previous call to 162.Fn log . 163As these messages are generated by the kernel itself, the facility will 164always be 165.Dv LOG_KERN . 166.Sh RETURN VALUES 167The 168.Fn kprintf , 169.Fn ksprintf , 170.Fn ksnprintf , 171.Fn kvprintf , 172.Fn kvsprintf , 173.Fn kvsnprintf , 174.Fn tprintf , 175and 176.Fn uprintf 177functions return the number of characters displayed. 178.Sh EXAMPLES 179This example demonstrates the use of the 180.Cm \&%b 181and 182.Cm \&%D 183conversion specifiers. 184The function 185.Bd -literal -offset indent 186void 187kprintf_test(void) 188{ 189 190 kprintf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE\en"); 191 kprintf("out: %4D\en", "AAAA", ":"); 192} 193.Ed 194.Pp 195will produce the following output: 196.Bd -literal -offset indent 197reg=3<BITTWO,BITONE> 198out: 41:41:41:41 199.Ed 200.Pp 201The call 202.Bd -literal -offset indent 203log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); 204.Ed 205.Pp 206will add the appropriate debug message at priority 207.Dq Li kern.debug 208to the system log. 209.Sh SEE ALSO 210.Xr printf 3 , 211.Xr syslog 3 212