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$ 28.\" 29.Dd September 8, 2006 30.Dt PRINTF 9 31.Os 32.Sh NAME 33.Nm printf , uprintf , tprintf, log 34.Nd formatted output conversion 35.Sh SYNOPSIS 36.In sys/types.h 37.In sys/systm.h 38.Ft int 39.Fn printf "const char *fmt" ... 40.Ft void 41.Fn tprintf "struct proc *p" "int pri" "const char *fmt" ... 42.Ft int 43.Fn uprintf "const char *fmt" ... 44.In sys/syslog.h 45.Ft void 46.Fn log "int pri" "const char *fmt" ... 47.Sh DESCRIPTION 48The 49.Xr printf 9 50family of functions are similar to the 51.Xr printf 3 52family of functions. 53The different functions each use a different output stream. 54The 55.Fn uprintf 56function outputs to the current process' controlling tty, while 57.Fn printf 58writes to the console as well as to the logging facility. 59The 60.Fn tprintf 61function outputs to the tty associated with the process 62.Fa p 63and the logging facility if 64.Fa pri 65is not \-1. 66The 67.Fn log 68function sends the message to the kernel logging facility, using 69the log level as indicated by 70.Fa pri , 71and to the console if no process is yet reading the log. 72.Pp 73Each of these related functions use the 74.Fa fmt 75parameter in the same manner as 76.Xr printf 3 . 77However, 78.Xr printf 9 79adds two other conversion specifiers. 80.Pp 81The 82.Cm \&%b 83identifier expects two arguments: an 84.Vt int 85and a 86.Vt "char *" . 87These are used as a register value and a print mask for decoding bitmasks. 88The print mask is made up of two parts: the base and the 89arguments. 90The base value is the output base expressed as an integer value; 91for example, \e10 gives octal and \e20 gives hexadecimal. 92The arguments are made up of a sequence of bit identifiers. 93Each bit identifier begins with an integer value which is the number of the 94bit (starting from 1) this identifier describes. 95The rest of the identifier is a string of characters containing the name of 96the bit. 97The string is terminated by either the bit number at the start of the next 98bit identifier or 99.Dv NUL 100for the last bit identifier. 101.Pp 102The 103.Cm \&%D 104identifier is meant to assist in hexdumps. 105It requires two arguments: a 106.Vt "u_char *" 107pointer and a 108.Vt "char *" 109string. 110The memory pointed to be the pointer is output in hexadecimal one byte at 111a time. 112The string is used as a delimiter between individual bytes. 113If present, a width directive will specify the number of bytes to display. 114By default, 16 bytes of data are output. 115.Pp 116The 117.Fn log 118function uses 119.Xr syslog 3 120level values 121.Dv LOG_DEBUG 122through 123.Dv LOG_EMERG 124for its 125.Fa pri 126parameter (mistakenly called 127.Sq priority 128here). 129Alternatively, if a 130.Fa pri 131of \-1 is given, the message will be appended to the last log message 132started by a previous call to 133.Fn log . 134As these messages are generated by the kernel itself, the facility will 135always be 136.Dv LOG_KERN . 137.Sh RETURN VALUES 138The 139.Fn printf 140and the 141.Fn uprintf 142functions return the number of characters displayed. 143.Sh EXAMPLES 144This example demonstrates the use of the 145.Cm \&%b 146and 147.Cm \&%D 148conversion specifiers. 149The function 150.Bd -literal -offset indent 151void 152printf_test(void) 153{ 154 155 printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE"); 156 printf("out: %4D\en", "AAAA", ":"); 157} 158.Ed 159.Pp 160will produce the following output: 161.Bd -literal -offset indent 162reg=3<BITTWO,BITONE> 163out: 41:41:41:41 164.Ed 165.Pp 166The call 167.Bd -literal -offset indent 168log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); 169.Ed 170.Pp 171will add the appropriate debug message at priority 172.Dq Li kern.debug 173to the system log. 174.Sh SEE ALSO 175.Xr printf 3 , 176.Xr syslog 3 177