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