Fri Jan 21 17:51:20 2011 UTC ()
Describe device_printf(9).

XXX Need symbolic link device_printf.9 -> kprintf.9.


(dyoung)
diff -r1.29 -r1.30 src/share/man/man9/kprintf.9
cvs diff -r1.29 -r1.30 src/share/man/man9/kprintf.9 (switch to unified diff)

--- src/share/man/man9/kprintf.9 2010/02/17 22:04:14 1.29
+++ src/share/man/man9/kprintf.9 2011/01/21 17:51:19 1.30
@@ -1,305 +1,314 @@ @@ -1,305 +1,314 @@
1.\" $NetBSD: kprintf.9,v 1.29 2010/02/17 22:04:14 cnst Exp $ 1.\" $NetBSD: kprintf.9,v 1.30 2011/01/21 17:51:19 dyoung Exp $
2.\" 2.\"
3.\" Copyright (c) 1998, 2002, 2007 The NetBSD Foundation, Inc. 3.\" Copyright (c) 1998, 2002, 2007, 2011 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Jeremy Cooper and by Jason R. Thorpe. 7.\" by Jeremy Cooper and by Jason R. Thorpe.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd September 4, 2009 30.Dd January 21, 2011
31.Dt KPRINTF 9 31.Dt KPRINTF 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
 34.Nm device_printf ,
34.Nm printf , 35.Nm printf ,
35.Nm snprintf , 36.Nm snprintf ,
36.Nm vprintf , 37.Nm vprintf ,
37.Nm vsnprintf , 38.Nm vsnprintf ,
38.Nm uprintf , 39.Nm uprintf ,
39.Nm ttyprintf , 40.Nm ttyprintf ,
40.Nm tprintf , 41.Nm tprintf ,
41.Nm aprint 42.Nm aprint
42.Nd kernel formatted output conversion 43.Nd kernel formatted output conversion
43.Sh SYNOPSIS 44.Sh SYNOPSIS
44.In sys/systm.h 45.In sys/systm.h
45.Ft void 46.Ft void
 47.Fn "device_printf" "device_t" "const char *format" "..."
 48.Ft void
46.Fn "printf" "const char *format" "..." 49.Fn "printf" "const char *format" "..."
47.Ft void 50.Ft void
48.Fn "printf_nolog" "const char *format" "..." 51.Fn "printf_nolog" "const char *format" "..."
49.Ft int 52.Ft int
50.Fn "snprintf" "char *buf" "size_t size" "const char *format" "..." 53.Fn "snprintf" "char *buf" "size_t size" "const char *format" "..."
51.In machine/stdarg.h 54.In machine/stdarg.h
52.Ft void 55.Ft void
53.Fn "vprintf" "const char *format" "va_list ap" 56.Fn "vprintf" "const char *format" "va_list ap"
54.Ft int 57.Ft int
55.Fn "vsnprintf" "char *buf" "size_t size" "const char *format" "va_list ap" 58.Fn "vsnprintf" "char *buf" "size_t size" "const char *format" "va_list ap"
56.Ft void 59.Ft void
57.Fn "uprintf" "const char *format" "..." 60.Fn "uprintf" "const char *format" "..."
58.Ft void 61.Ft void
59.Fn "ttyprintf" "struct tty *tty" "const char *format" "..." 62.Fn "ttyprintf" "struct tty *tty" "const char *format" "..."
60.In sys/tprintf.h 63.In sys/tprintf.h
61.Ft tpr_t 64.Ft tpr_t
62.Fn "tprintf_open" "struct proc *p" 65.Fn "tprintf_open" "struct proc *p"
63.Ft void 66.Ft void
64.Fn "tprintf" "tpr_t tpr" "const char *format" "..." 67.Fn "tprintf" "tpr_t tpr" "const char *format" "..."
65.Ft void 68.Ft void
66.Fn "tprintf_close" "tpr_t tpr" 69.Fn "tprintf_close" "tpr_t tpr"
67.Ft void 70.Ft void
68.Fn "aprint_normal" "const char *format" "..." 71.Fn "aprint_normal" "const char *format" "..."
69.Ft void 72.Ft void
70.Fn "aprint_naive" "const char *format" "..." 73.Fn "aprint_naive" "const char *format" "..."
71.Ft void 74.Ft void
72.Fn "aprint_verbose" "const char *format" "..." 75.Fn "aprint_verbose" "const char *format" "..."
73.Ft void 76.Ft void
74.Fn "aprint_debug" "const char *format" "..." 77.Fn "aprint_debug" "const char *format" "..."
75.Ft void 78.Ft void
76.Fn "aprint_error" "const char *format" "..." 79.Fn "aprint_error" "const char *format" "..."
77.Ft void 80.Ft void
78.Fn "aprint_normal_dev" "device_t" "const char *format" "..." 81.Fn "aprint_normal_dev" "device_t" "const char *format" "..."
79.Ft void 82.Ft void
80.Fn "aprint_naive_dev" "device_t" "const char *format" "..." 83.Fn "aprint_naive_dev" "device_t" "const char *format" "..."
81.Ft void 84.Ft void
82.Fn "aprint_verbose_dev" "device_t" "const char *format" "..." 85.Fn "aprint_verbose_dev" "device_t" "const char *format" "..."
83.Ft void 86.Ft void
84.Fn "aprint_debug_dev" "device_t" "const char *format" "..." 87.Fn "aprint_debug_dev" "device_t" "const char *format" "..."
85.Ft void 88.Ft void
86.Fn "aprint_error_dev" "device_t" "const char *format" "..." 89.Fn "aprint_error_dev" "device_t" "const char *format" "..."
87.Ft void 90.Ft void
88.Fn "aprint_normal_ifnet" "struct ifnet *" "const char *format" "..." 91.Fn "aprint_normal_ifnet" "struct ifnet *" "const char *format" "..."
89.Ft void 92.Ft void
90.Fn "aprint_naive_ifnet" "struct ifnet *" "const char *format" "..." 93.Fn "aprint_naive_ifnet" "struct ifnet *" "const char *format" "..."
91.Ft void 94.Ft void
92.Fn "aprint_verbose_ifnet" "struct ifnet *" "const char *format" "..." 95.Fn "aprint_verbose_ifnet" "struct ifnet *" "const char *format" "..."
93.Ft void 96.Ft void
94.Fn "aprint_debug_ifnet" "struct ifnet *" "const char *format" "..." 97.Fn "aprint_debug_ifnet" "struct ifnet *" "const char *format" "..."
95.Ft void 98.Ft void
96.Fn "aprint_error_ifnet" "struct ifnet *" "const char *format" "..." 99.Fn "aprint_error_ifnet" "struct ifnet *" "const char *format" "..."
97.Ft int 100.Ft int
98.Fn "aprint_get_error_count" "void" 101.Fn "aprint_get_error_count" "void"
99.Sh DESCRIPTION 102.Sh DESCRIPTION
100The 103The
101.Fn printf 104.Fn printf
102family of functions allows the kernel to send formatted messages to various 105family of functions allows the kernel to send formatted messages to various
103output devices. 106output devices.
104The functions 107The functions
105.Fn printf 108.Fn printf
106and 109and
107.Fn vprintf 110.Fn vprintf
108send formatted strings to the system console. 111send formatted strings to the system console.
109The 112The
 113.Fn device_printf
 114function is identical to
 115.Fn printf ,
 116except that it prefixes the log message with the corresponding
 117device name.
 118The
110.Fn printf_nolog 119.Fn printf_nolog
111function is identical to 120function is identical to
112.Fn printf , 121.Fn printf ,
113except it does not send the data to the system log. 122except it does not send the data to the system log.
114The functions 123The functions
115.Fn snprintf 124.Fn snprintf
116and 125and
117.Fn vsnprintf 126.Fn vsnprintf
118write output to a string buffer. 127write output to a string buffer.
119These four functions work similarly to their user space counterparts, 128These four functions work similarly to their user space counterparts,
120and are not described in detail here. 129and are not described in detail here.
121.Pp 130.Pp
122The functions 131The functions
123.Fn uprintf 132.Fn uprintf
124and 133and
125.Fn ttyprintf 134.Fn ttyprintf
126send formatted strings to the current process's controlling tty and a specific 135send formatted strings to the current process's controlling tty and a specific
127tty, respectively. 136tty, respectively.
128.Pp 137.Pp
129The 138The
130.Fn tprintf 139.Fn tprintf
131function sends formatted strings to a process's controlling tty, 140function sends formatted strings to a process's controlling tty,
132via a handle of type tpr_t. 141via a handle of type tpr_t.
133This allows multiple write operations to the tty with a guarantee that the 142This allows multiple write operations to the tty with a guarantee that the
134tty will be valid across calls. 143tty will be valid across calls.
135A handle is acquired by calling 144A handle is acquired by calling
136.Fn tprintf_open 145.Fn tprintf_open
137with the target process as an argument. 146with the target process as an argument.
138This handle must be closed with a matching call to 147This handle must be closed with a matching call to
139.Fn tprintf_close . 148.Fn tprintf_close .
140.Pp 149.Pp
141The functions 150The functions
142.Fn aprint_normal , 151.Fn aprint_normal ,
143.Fn aprint_naive , 152.Fn aprint_naive ,
144.Fn aprint_verbose , 153.Fn aprint_verbose ,
145.Fn aprint_debug , 154.Fn aprint_debug ,
146and 155and
147.Fn aprint_error 156.Fn aprint_error
148are intended to be used to print 157are intended to be used to print
149.Xr autoconf 9 158.Xr autoconf 9
150messages. 159messages.
151Their verbosity depends on flags set in the 160Their verbosity depends on flags set in the
152.Va boothowto 161.Va boothowto
153variable, through options passed during bootstrap; see 162variable, through options passed during bootstrap; see
154.Xr boothowto 9 163.Xr boothowto 9
155and 164and
156.Sx Interactive mode 165.Sx Interactive mode
157in 166in
158.Xr boot 8 : 167.Xr boot 8 :
159.Bl -tag -width AB_VERBOSE 168.Bl -tag -width AB_VERBOSE
160.It Dv AB_SILENT 169.It Dv AB_SILENT
161silent mode, enabled by 170silent mode, enabled by
162.Ic boot 171.Ic boot
163.Fl z . 172.Fl z .
164.It Dv AB_QUIET 173.It Dv AB_QUIET
165quiet mode, enabled by 174quiet mode, enabled by
166.Ic boot 175.Ic boot
167.Fl q . 176.Fl q .
168.It Dv AB_VERBOSE 177.It Dv AB_VERBOSE
169verbose mode, enabled by 178verbose mode, enabled by
170.Ic boot 179.Ic boot
171.Fl v . 180.Fl v .
172.It Dv AB_DEBUG 181.It Dv AB_DEBUG
173debug mode, enabled by 182debug mode, enabled by
174.Ic boot 183.Ic boot
175.Fl x . 184.Fl x .
176.El 185.El
177.Pp 186.Pp
178The 187The
179.Fn aprint_* 188.Fn aprint_*
180functions have the following behaviour, based on the above 189functions have the following behaviour, based on the above
181mentioned flags: 190mentioned flags:
182.Bl -tag -width Xaprint_verboseXXX 191.Bl -tag -width Xaprint_verboseXXX
183.It Fn aprint_normal 192.It Fn aprint_normal
184Sends to the console unless 193Sends to the console unless
185.Dv AB_QUIET 194.Dv AB_QUIET
186is set. 195is set.
187Always sends to the log. 196Always sends to the log.
188.It Fn aprint_naive 197.It Fn aprint_naive
189Sends to the console only if 198Sends to the console only if
190.Dv AB_QUIET 199.Dv AB_QUIET
191is set. 200is set.
192Never sends to the log. 201Never sends to the log.
193.It Fn aprint_verbose 202.It Fn aprint_verbose
194Sends to the console only if 203Sends to the console only if
195.Dv AB_VERBOSE 204.Dv AB_VERBOSE
196is set. 205is set.
197Always sends to the log. 206Always sends to the log.
198.It Fn aprint_debug 207.It Fn aprint_debug
199Sends to the console and the log only if 208Sends to the console and the log only if
200.Dv AB_DEBUG 209.Dv AB_DEBUG
201is set. 210is set.
202.It Fn aprint_error 211.It Fn aprint_error
203Like 212Like
204.Fn aprint_normal , 213.Fn aprint_normal ,
205but also keeps track of the number of times called. 214but also keeps track of the number of times called.
206This allows a subsystem to report the number of errors that occurred 215This allows a subsystem to report the number of errors that occurred
207during a quiet or silent initialization phase. 216during a quiet or silent initialization phase.
208.El 217.El
209.Pp 218.Pp
210For the 219For the
211.Fn aprint_* 220.Fn aprint_*
212functions there are two additional families of functions with the 221functions there are two additional families of functions with the
213suffixes 222suffixes
214.Dv _dev 223.Dv _dev
215and 224and
216.Dv _ifnet 225.Dv _ifnet
217which work like their counterparts without the suffixes, except that 226which work like their counterparts without the suffixes, except that
218they take a 227they take a
219.Ft device_t 228.Ft device_t
220and 229and
221.Ft struct ifnet * , 230.Ft struct ifnet * ,
222respectively, as first argument, 231respectively, as first argument,
223and prefix the log message with the 232and prefix the log message with the
224corresponding device or interface name. 233corresponding device or interface name.
225.Pp 234.Pp
226The 235The
227.Fn aprint_get_error_count 236.Fn aprint_get_error_count
228function reports the number of errors and resets the counter to 0. 237function reports the number of errors and resets the counter to 0.
229.Pp 238.Pp
230If 239If
231.Dv AB_SILENT 240.Dv AB_SILENT
232is set, none of the autoconfiguration message printing routines send output 241is set, none of the autoconfiguration message printing routines send output
233to the console. 242to the console.
234The 243The
235.Dv AB_VERBOSE 244.Dv AB_VERBOSE
236and 245and
237.Dv AB_DEBUG 246.Dv AB_DEBUG
238flags override 247flags override
239.Dv AB_SILENT . 248.Dv AB_SILENT .
240.Sh RETURN VALUES 249.Sh RETURN VALUES
241The 250The
242.Fn snprintf 251.Fn snprintf
243and 252and
244.Fn vsnprintf 253.Fn vsnprintf
245functions return the number of characters placed in the buffer 254functions return the number of characters placed in the buffer
246.Fa buf . 255.Fa buf .
247This is different to the user-space functions of the same name. 256This is different to the user-space functions of the same name.
248.Pp 257.Pp
249The 258The
250.Fn tprintf_open 259.Fn tprintf_open
251function returns 260function returns
252.Dv NULL 261.Dv NULL
253if no terminal handle could be acquired. 262if no terminal handle could be acquired.
254.Sh SEE ALSO 263.Sh SEE ALSO
255.Xr printf 1 , 264.Xr printf 1 ,
256.Xr printf 3 , 265.Xr printf 3 ,
257.Xr snprintb 3 , 266.Xr snprintb 3 ,
258.Xr boot 8 , 267.Xr boot 8 ,
259.Xr autoconf 9 , 268.Xr autoconf 9 ,
260.Xr boothowto 9 269.Xr boothowto 9
261.Sh CODE REFERENCES 270.Sh CODE REFERENCES
262.Pa sys/kern/subr_prf.c 271.Pa sys/kern/subr_prf.c
263.Sh HISTORY 272.Sh HISTORY
264The 273The
265.Fn sprintf 274.Fn sprintf
266and 275and
267.Fn vsprintf 276.Fn vsprintf
268unsized string formatting functions are supported for compatibility only, 277unsized string formatting functions are supported for compatibility only,
269and are not documented here. 278and are not documented here.
270New code should use the size-limited 279New code should use the size-limited
271.Fn snprintf 280.Fn snprintf
272and 281and
273.Fn vsnprintf 282.Fn vsnprintf
274functions instead. 283functions instead.
275.Pp 284.Pp
276In 285In
277.Nx 1.5 286.Nx 1.5
278and earlier, 287and earlier,
279.Fn printf 288.Fn printf
280supported more format strings than the user space 289supported more format strings than the user space
281.Fn printf . 290.Fn printf .
282These nonstandard format strings are no longer supported. 291These nonstandard format strings are no longer supported.
283For the functionality provided by the former 292For the functionality provided by the former
284.Li %b 293.Li %b
285format string, see 294format string, see
286.Xr snprintb 3 . 295.Xr snprintb 3 .
287.Pp 296.Pp
288The 297The
289.Fn aprint_normal , 298.Fn aprint_normal ,
290.Fn aprint_naive , 299.Fn aprint_naive ,
291.Fn aprint_verbose , 300.Fn aprint_verbose ,
292and 301and
293.Fn aprint_debug 302.Fn aprint_debug
294functions first appeared in 303functions first appeared in
295.Bsx . 304.Bsx .
296.Sh BUGS 305.Sh BUGS
297The 306The
298.Fn uprintf 307.Fn uprintf
299and 308and
300.Fn ttyprintf 309.Fn ttyprintf
301functions should be used sparingly, if at all. 310functions should be used sparingly, if at all.
302Where multiple lines of output are required to reach a process's 311Where multiple lines of output are required to reach a process's
303controlling terminal, 312controlling terminal,
304.Fn tprintf 313.Fn tprintf
305is preferred. 314is preferred.