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