172 lines
4.6 KiB
Groff
172 lines
4.6 KiB
Groff
.\"
|
|
.\" Copyright (c) 2001 Andrew R. Reiter
|
|
.\" Copyritht (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 August 10, 2004
|
|
.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 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 \&%b and \&%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
|