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