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.5 2008/07/18 00:28:04 swildner Exp $ 29.\" 30.Dd July 17, 2008 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 krateprintf , 41.Nm tprintf , 42.Nm uprintf , 43.Nm log 44.Nd formatted output conversion 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/systm.h 48.Ft int 49.Fn kprintf "const char *format" ... 50.Ft int 51.Fn ksprintf "char *str" "const char *format" ... 52.Ft int 53.Fn ksnprintf "char *str" "size_t size" "const char *format" ... 54.Ft int 55.Fn kvprintf "const char *format" "__va_list ap" 56.Ft int 57.Fn kvsprintf "char *str" "const char *format" "__va_list ap" 58.Ft int 59.Fn kvsnprintf "char *str" "size_t size" "const char *format" "__va_list ap" 60.Ft void 61.Fn krateprintf "struct krate *rate" "const char *format" ... 62.Ft int 63.Fn tprintf "struct proc *p" "int pri" "const char *format" ... 64.Ft int 65.Fn uprintf "const char *format" ... 66.In sys/syslog.h 67.Ft int 68.Fn log "int pri" "const char *format" ... 69.Sh DESCRIPTION 70The 71.Nm 72family of functions are similar to the 73.Xr printf 3 74family of functions. 75The different functions each use a different output stream. 76The 77.Fn uprintf 78function outputs to the current process' controlling tty, while 79.Fn kprintf , 80.Fn ksprintf , 81.Fn ksnprintf , 82.Fn kvprintf , 83.Fn kvsprintf 84and 85.Fn kvsnprintf 86write to the console as well as to the logging facility. 87The 88.Fn tprintf 89function outputs to the tty associated with the process 90.Fa p 91and the logging facility if 92.Fa pri 93is not \-1. 94The 95.Fn log 96function sends the message to the kernel logging facility, using 97the log level as indicated by 98.Fa pri . 99.Pp 100Each of these related functions use the 101.Fa format , 102.Fa str , 103.Fa size 104and 105.Fa va 106parameters in the same manner as 107.Xr printf 3 . 108However, the 109.Nm 110functions add two other conversion specifiers to 111.Fa format : 112.Pp 113The 114.Cm \&%b 115identifier expects two arguments: an 116.Vt int 117and a 118.Vt "char *" . 119These are used as a register value and a print mask for decoding bitmasks. 120The print mask is made up of two parts: the base and the 121arguments. 122The base value is the output base expressed as an integer value; 123for example, \e10 gives octal and \e20 gives hexadecimal. 124The arguments are made up of a sequence of bit identifiers. 125Each bit identifier begins with an integer value which is the number of the 126bit (starting from 1) this identifier describes. 127The rest of the identifier is a string of characters containing the name of 128the bit. 129The string is terminated by either the bit number at the start of the next 130bit identifier or 131.Dv NUL 132for the last bit identifier. 133.Pp 134The 135.Cm \&%D 136identifier is meant to assist in hexdumps. 137It requires two arguments: a 138.Vt "u_char *" 139pointer and a 140.Vt "char *" 141string. 142The memory pointed to be the pointer is output in hexadecimal one byte at 143a time. 144The string is used as a delimiter between individual bytes. 145If present, a width directive will specify the number of bytes to display. 146By default, 16 bytes of data are output. 147.Pp 148The 149.Fn log 150function uses 151.Xr syslog 3 152level values 153.Dv LOG_DEBUG 154through 155.Dv LOG_EMERG 156for its 157.Fa pri 158parameter (mistakenly called 159.Sq priority 160here). 161Alternatively, if a 162.Fa pri 163of \-1 is given, the message will be appended to the last log message 164started by a previous call to 165.Fn log . 166As these messages are generated by the kernel itself, the facility will 167always be 168.Dv LOG_KERN . 169.Pp 170The 171.Fn krateprintf 172function is a rate controlled version of 173.Fn kprintf . 174The 175.Fa freq 176member of the 177.Vt struct krate 178pointed to by 179.Fa rate 180must be initialized with the desired reporting frequency. 181A 182.Fa freq 183of 0 will result in no output. 184Initializing 185.Fa count 186to a negative value allows an initial burst. 187.Sh RETURN VALUES 188The 189.Fn kprintf , 190.Fn ksprintf , 191.Fn ksnprintf , 192.Fn kvprintf , 193.Fn kvsprintf , 194.Fn kvsnprintf , 195.Fn tprintf , 196.Fn uprintf , 197and 198.Fn log 199functions return the number of characters displayed. 200.Sh EXAMPLES 201This example demonstrates the use of the 202.Cm \&%b 203and 204.Cm \&%D 205conversion specifiers. 206The function 207.Bd -literal -offset indent 208void 209kprintf_test(void) 210{ 211 212 kprintf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE\en"); 213 kprintf("out: %4D\en", "AAAA", ":"); 214} 215.Ed 216.Pp 217will produce the following output: 218.Bd -literal -offset indent 219reg=3<BITTWO,BITONE> 220out: 41:41:41:41 221.Ed 222.Pp 223The call 224.Bd -literal -offset indent 225log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); 226.Ed 227.Pp 228will add the appropriate debug message at priority 229.Dq Li kern.debug 230to the system log. 231.Sh SEE ALSO 232.Xr printf 3 , 233.Xr syslog 3 234