diff options
Diffstat (limited to 'share/man/man9/printf.9')
| -rw-r--r-- | share/man/man9/printf.9 | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/share/man/man9/printf.9 b/share/man/man9/printf.9 new file mode 100644 index 000000000000..571e7e638c36 --- /dev/null +++ b/share/man/man9/printf.9 @@ -0,0 +1,175 @@ +.\" +.\" Copyright (c) 2001 Andrew R. Reiter +.\" Copyright (c) 2004 Joerg Wunsch +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 8, 2006 +.Dt PRINTF 9 +.Os +.Sh NAME +.Nm printf , uprintf , tprintf, log +.Nd formatted output conversion +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn printf "const char *fmt" ... +.Ft void +.Fn tprintf "struct proc *p" "int pri" "const char *fmt" ... +.Ft int +.Fn uprintf "const char *fmt" ... +.In sys/syslog.h +.Ft void +.Fn log "int pri" "const char *fmt" ... +.Sh DESCRIPTION +The +.Xr printf 9 +family of functions are similar to the +.Xr printf 3 +family of functions. +The different functions each use a different output stream. +The +.Fn uprintf +function outputs to the current process' controlling tty, while +.Fn printf +writes to the console as well as to the logging facility. +The +.Fn tprintf +function outputs to the tty associated with the process +.Fa p +and the logging facility if +.Fa pri +is not \-1. +The +.Fn log +function sends the message to the kernel logging facility, using +the log level as indicated by +.Fa pri . +.Pp +Each of these related functions use the +.Fa fmt +parameter in the same manner as +.Xr printf 3 . +However, +.Xr printf 9 +adds two other conversion specifiers. +.Pp +The +.Cm \&%b +identifier expects two arguments: an +.Vt int +and a +.Vt "char *" . +These are used as a register value and a print mask for decoding bitmasks. +The print mask is made up of two parts: the base and the +arguments. +The base value is the output base expressed as an integer value; +for example, \e10 gives octal and \e20 gives hexadecimal. +The arguments are made up of a sequence of bit identifiers. +Each bit identifier begins with an integer value which is the number of the +bit (starting from 1) this identifier describes. +The rest of the identifier is a string of characters containing the name of +the bit. +The string is terminated by either the bit number at the start of the next +bit identifier or +.Dv NUL +for the last bit identifier. +.Pp +The +.Cm \&%D +identifier is meant to assist in hexdumps. +It requires two arguments: a +.Vt "u_char *" +pointer and a +.Vt "char *" +string. +The memory pointed to be the pointer is output in hexadecimal one byte at +a time. +The string is used as a delimiter between individual bytes. +If present, a width directive will specify the number of bytes to display. +By default, 16 bytes of data are output. +.Pp +The +.Fn log +function uses +.Xr syslog 3 +level values +.Dv LOG_DEBUG +through +.Dv LOG_EMERG +for its +.Fa pri +parameter (mistakenly called +.Sq priority +here). +Alternatively, if a +.Fa pri +of \-1 is given, the message will be appended to the last log message +started by a previous call to +.Fn log . +As these messages are generated by the kernel itself, the facility will +always be +.Dv LOG_KERN . +.Sh RETURN VALUES +The +.Fn printf +and the +.Fn uprintf +functions return the number of characters displayed. +.Sh EXAMPLES +This example demonstrates the use of the +.Cm \&%b +and +.Cm \&%D +conversion specifiers. +The function +.Bd -literal -offset indent +void +printf_test(void) +{ + + printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE\en"); + printf("out: %4D\en", "AAAA", ":"); +} +.Ed +.Pp +will produce the following output: +.Bd -literal -offset indent +reg=3<BITTWO,BITONE> +out: 41:41:41:41 +.Ed +.Pp +The call +.Bd -literal -offset indent +log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); +.Ed +.Pp +will add the appropriate debug message at priority +.Dq Li kern.debug +to the system log. +.Sh SEE ALSO +.Xr printf 3 , +.Xr syslog 3 |