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