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.\" 29.Dd December 21, 2012 30.Dt KPRINTF 9 31.Os 32.Sh NAME 33.Nm kprintf , 34.Nm ksprintf , 35.Nm ksnprintf , 36.Nm kvprintf , 37.Nm kvsprintf , 38.Nm kvsnprintf , 39.Nm krateprintf , 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 krateprintf "struct krate *rate" "const char *format" ... 61.Ft int 62.Fn tprintf "struct proc *p" "int pri" "const char *format" ... 63.Ft int 64.Fn uprintf "const char *format" ... 65.In sys/syslog.h 66.Ft int 67.Fn log "int pri" "const char *format" ... 68.Sh DESCRIPTION 69The 70.Nm 71family of functions are similar to the 72.Xr printf 3 73family of functions. 74The different functions each use a different output stream. 75The 76.Fn uprintf 77function outputs to the current process' controlling tty, while 78.Fn kprintf , 79.Fn ksprintf , 80.Fn ksnprintf , 81.Fn kvprintf , 82.Fn kvsprintf 83and 84.Fn kvsnprintf 85write to the console as well as to the logging facility. 86The 87.Fn tprintf 88function outputs to the tty associated with the process 89.Fa p 90and the logging facility if 91.Fa pri 92is not \-1. 93The 94.Fn log 95function sends the message to the kernel logging facility, using 96the log level as indicated by 97.Fa pri . 98.Pp 99Each of these related functions use the 100.Fa format , 101.Fa str , 102.Fa size 103and 104.Fa va 105parameters in the same manner as 106.Xr printf 3 . 107However, the 108.Nm 109functions add another conversion specifier to 110.Fa format : 111.Pp 112The 113.Cm \&%b 114identifier expects two arguments: an 115.Vt int 116and a 117.Vt "char *" . 118These are used as a register value and a print mask for decoding bitmasks. 119The print mask is made up of two parts: the base and the 120arguments. 121The base value is the output base expressed as an integer value; 122for example, \e10 gives octal and \e20 gives hexadecimal. 123The arguments are made up of a sequence of bit identifiers. 124Each bit identifier begins with an integer value which is the number of the 125bit (starting from 1) this identifier describes. 126The rest of the identifier is a string of characters containing the name of 127the bit. 128The string is terminated by either the bit number at the start of the next 129bit identifier or 130.Dv NUL 131for the last bit identifier. 132.Pp 133The 134.Fn log 135function uses 136.Xr syslog 3 137level values 138.Dv LOG_DEBUG 139through 140.Dv LOG_EMERG 141for its 142.Fa pri 143parameter (mistakenly called 144.Sq priority 145here). 146Alternatively, if a 147.Fa pri 148of \-1 is given, the message will be appended to the last log message 149started by a previous call to 150.Fn log . 151As these messages are generated by the kernel itself, the facility will 152always be 153.Dv LOG_KERN . 154.Pp 155The 156.Fn krateprintf 157function is a rate controlled version of 158.Fn kprintf . 159The 160.Fa freq 161member of the 162.Vt struct krate 163pointed to by 164.Fa rate 165must be initialized with the desired reporting frequency. 166A 167.Fa freq 168of 0 will result in no output. 169Initializing 170.Fa count 171to a negative value allows an initial burst. 172.Sh RETURN VALUES 173The 174.Fn kprintf , 175.Fn ksprintf , 176.Fn ksnprintf , 177.Fn kvprintf , 178.Fn kvsprintf , 179.Fn kvsnprintf , 180.Fn tprintf , 181.Fn uprintf , 182and 183.Fn log 184functions return the number of characters displayed. 185.Sh EXAMPLES 186This example demonstrates the use of the 187.Cm \&%b 188conversion specifier. 189The function 190.Bd -literal -offset indent 191void 192kprintf_test(void) 193{ 194 195 kprintf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE\en"); 196} 197.Ed 198.Pp 199will produce the following output: 200.Bd -literal -offset indent 201reg=3<BITTWO,BITONE> 202.Ed 203.Pp 204The call 205.Bd -literal -offset indent 206log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); 207.Ed 208.Pp 209will add the appropriate debug message at priority 210.Dq Li kern.debug 211to the system log. 212.Sh SEE ALSO 213.Xr printf 3 , 214.Xr syslog 3 215