131 lines
3.8 KiB
Groff
131 lines
3.8 KiB
Groff
.\"
|
|
.\" Copyright (c) 2001 Andrew R. Reiter
|
|
.\" 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 April 25, 2001
|
|
.Dt PRINTF 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm printf , uprintf , tprintf
|
|
.Nd formatted output conversion
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <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" "..."
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Xr printf 9
|
|
family of functions are similar to the
|
|
.Xr printf 3
|
|
family of functions.
|
|
The three 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.
|
|
.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, \\10 gives octal and \\20 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.
|
|
.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\\n", 3, "\\10\\2BITTWO\\1BITONE\\n");
|
|
printf("out: %4D\\n", "AAAA", ":");
|
|
}
|
|
.Ed
|
|
.Pp
|
|
will produce the following output:
|
|
.Bd -literal -offset indent
|
|
reg=3<BITTWO,BITONE>
|
|
out: 41:41:41:41
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr printf 3
|