| blob | 9b620c7ff47322728bb5a3407a71b88aca9ad04c |
1 .\"
2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
5 .\"
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
10 .\"
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
16 .\"
17 .\"
18 .\" Copyright 1989 AT&T
19 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
20 .\" Copyright 2016 Nexenta Systems, Inc.
21 .\"
22 .Dd Dec 1, 2016
23 .Dt CMN_ERR 9F
24 .Os
25 .Sh NAME
26 .Nm cmn_err, dev_err, vcmn_err, zcmn_err, vzcmn_err
27 .Nd display an error message or panic the system
28 .Sh SYNOPSIS
29 .In sys/cmn_err.h
30 .In sys/ddi.h
31 .In sys/sunddi.h
32 .Ft void
33 .Fo cmn_err
34 .Fa "int level"
35 .Fa "char *format"
36 .Fa ...
37 .Fc
38 .Ft void
39 .Fo dev_err
40 .Fa "dev_info_t *dip"
41 .Fa "int level"
42 .Fa "char *format"
43 .Fa ...
44 .Fc
45 .In sys/varargs.h
46 .Ft void
47 .Fo vcmn_err
48 .Fa "int level"
49 .Fa "char *format"
50 .Fa "va_list ap"
51 .Fc
52 .In sys/types.h
53 .Ft void
54 .Fo zcmn_err
55 .Fa "zoneid_t zoneid"
56 .Fa "int level"
57 .Fa "char *format"
58 .Fa ...
59 .Fc
60 .Ft void
61 .Fo vzcmn_err
62 .Fa "zoneid_t zoneid"
63 .Fa "int level"
64 .Fa "char *format"
65 .Fa "va_list ap"
66 .Fc
67 .Sh INTERFACE LEVEL
68 Architecture independent level 1 (DDI/DKI).
69 .Sh PARAMETERS
70 .Ss Fn cmn_err
71 .Bl -tag -width Ds
72 .It Fa level
73 A constant indicating the severity of the error condition.
74 .It Fa format
75 Message to be displayed.
76 .El
77 .Ss Fn dev_err
78 The
79 .Fn dev_err
80 function works exactly like
81 .Fn cmn_err ,
82 but includes an additional argument:
83 .Bl -tag -width Ds
84 .It Fa dip
85 A pointer to the device's
86 .Ft dev_info
87 structure.
88 .El
89 .Ss Fn vcmn_err
90 The
91 .Fn vcmn_err
92 function takes
93 .Fa level
94 and
95 .Fa format
96 as described for
97 .Fn cmn_err ,
98 but its third argument is different:
99 .Bl -tag -width Ds
100 .It Fa ap
101 Variable argument list passed to the function.
102 .El
103 .Ss Fn zcmn_err
104 The
105 .Fn zcmn_err
106 function works exactly like
107 .Fn cmn_err ,
108 but includes an additional argument:
109 .Bl -tag -width Ds
110 .It Fa zoneid
111 Zone to which log messages should be directed.
112 See
113 .Xr zones 5 .
114 .El
115 .Ss Fn vzcmn_err
116 The
117 .Fn vzcmn_err
118 function works exactly like
119 .Fn vcmn_err ,
120 but includes an additional argument:
121 .Bl -tag -width Ds
122 .It Fa zoneid
123 Zone to which log messages should be directed.
124 See
125 .Xr zones 5 .
126 .El
127 .Sh DESCRIPTION
128 .Ss Fn cmn_err
129 The
130 .Fn cmn_err
131 function displays a specified message on the console.
132 .Fn cmn_err
133 can also panic the system.
134 When the system panics, it attempts to save recent changes to data, display a
135 .Qq panic message
136 on the console, attempt to write a core file, and halt system processing.
137 See the
138 .Sy CE_PANIC
139 .Fa level
140 below.
141 .Pp
142 .Fa level
143 is a constant indicating the severity of the error condition.
144 The four severity levels are:
145 .Bl -tag -width "CE_PANIC"
146 .It Sy CE_CONT
147 Used to continue another message or to display an informative message not
148 associated with an error.
149 Note that multiple
150 .Sy CE_CONT
151 messages without a newline may or may not appear on the system console or in the
152 system log as a single line message.
153 A single line message may be produced by constructing the message with
154 .Xr sprintf 9F
155 or
156 .Xr vsprintf 9F
157 before calling
158 .Fn cmn_err .
159 .It Sy CE_NOTE
160 Used to display a message preceded with
161 .Sy NOTICE .
162 This message is used to report system events that do not necessarily require
163 user action, but may interest the system administrator.
164 For example, a message saying that a sector on a disk needs to be accessed
165 repeatedly before it can be accessed correctly might be noteworthy.
166 .It Sy CE_WARN
167 Used to display a message preceded with
168 .Sy WARNING .
169 This message is used to report system events that require immediate attention,
170 such as those where if an action is not taken, the system may panic.
171 For example, when a peripheral device does not initialize correctly, this level
172 should be used.
173 .It Sy CE_PANIC
174 Used to display a message preceded with
175 .Qq Sy panic ,
176 and to panic the system.
177 Drivers should specify this level only under the most severe conditions or when
178 debugging a driver.
179 A valid use of this level is when the system cannot continue to function.
180 If the error is recoverable, or not essential to continued system operation, do
181 not panic the system.
182 .El
183 .Pp
184 The
185 .Fa format
186 is identical to the one described in
187 .Xr sprintf 9F
188 with additional meaning of the first character affecting where the message will
189 be written:
190 .Bl -tag -width Ds
191 .It Sy \!
192 The message goes only to the system log.
193 .It Sy ^
194 The message goes only to the console.
195 .It Sy \?
196 If
197 .Fa level
198 is also
199 .Sy CE_CONT ,
200 the message is always sent to the system log, but is only written to the console
201 when the system has been booted in verbose mode.
202 See
203 .Xr kernel 1M .
204 If neither condition is met, the
205 .Qq Sy \?
206 character has no effect and is simply ignored.
207 .El
208 .Pp
209 Refer to
210 .Xr syslogd 1M
211 to determine where the system log is written.
212 .Pp
213 The
214 .Fn cmn_err
215 function sends log messages to the log of the global zone.
216 .Fn cmn_err
217 appends a
218 .Sy \en
219 to each
220 .Fa format ,
221 except when
222 .Fa level
223 is
224 .Sy CE_CONT .
225 .Ss Fn dev_err
226 With the exception of its first argument
227 .Pq Fa dip ,
228 .Fn dev_err
229 is identical to
230 .Fn cmn_err .
231 .Fa dip
232 is a pointer to a device's
233 .Ft dev_info
234 structure, which is used to prepend the driver name and instance number to the
235 message.
236 The driver name and instance number are retrieved using
237 .Xr ddi_driver_name 9F
238 and
239 .Xr ddi_get_instance 9F .
240 .Ss Fn vcmn_err
241 The
242 .Fn vcmn_err
243 function is identical to
244 .Fn cmn_err
245 except that its last argument,
246 .Fa ap ,
247 is a pointer to a variable list of arguments.
248 .Fa ap
249 contains the list of arguments used by the conversion specifications in
250 .Fa format .
251 .Fa ap
252 must be initialized by calling
253 .Xr va_start 9F .
254 .Xr va_end 9F
255 is used to clean up and must be called after each traversal of the list.
256 Multiple traversals of the argument list, each bracketed by
257 .Xr va_start 9F
258 and
259 .Xr va_end 9F ,
260 are possible.
261 .Ss Fn zcmn_err
262 With the exception of its first argument
263 .Pq Fa zoneid ,
264 .Fn zcmn_err
265 is identical to
266 .Fn cmn_err .
267 .Fa zoneid
268 is the numeric ID of the zone to which the message should be directed.
269 Note that
270 .Fa zoneid
271 only has an effect if the message is sent to the system log.
272 Using
273 .Fa zoneid
274 will cause messages to be sent to the log associated with the specified local
275 zone rather than the log in the global zone.
276 This is accomplished by the message being received and processed by the
277 .Xr syslogd 1M
278 process running in the specified zone instead of the one running in the global
279 zone.
280 You can retrieve a process zone ID from its credential structure using
281 .Xr crgetzoneid 9F .
282 .Ss Fn vzcmn_err
283 With the exception of its first argument
284 .Pq Fa zoneid ,
285 .Fn vzcmn_err
286 is identical to
287 .Fn vcmn_err .
288 See the description of
289 .Fn zcmn_err
290 above for an explanation on how the
291 .Fa zoneid
292 argument is handled.
293 .Sh CONTEXT
294 The
295 .Fn cmn_err
296 function can be called from user, kernel, interrupt, or high-level interrupt
297 context.
298 .Sh RETURN VALUES
299 None.
300 However, if an unknown
301 .Fa level
302 is passed to
303 .Fn cmn_err ,
304 the following panic error message is displayed:
305 .Bd -literal
306 panic: unknown level in cmn_err (level=level, msg=format)
307 .Ed
308 .Sh EXAMPLES
309 .Bl -tag -width Ds
310 .It Sy Example 1 No Using Fn cmn_err
311 This first example shows how
312 .Fn cmn_err
313 can record tracing and debugging information only in the system log
314 .Pq lines 17 ;
315 display problems with a device only on the system console
316 .Pq line 23 ;
317 or display problems with the device on both the system console and in the system
318 log
319 .Pq line 28 .
320 .Bd -literal
321 1 struct reg {
322 2 uchar_t data;
323 3 uchar_t csr;
324 4 };
325 5
326 6 struct xxstate {
327 7 ...
328 8 dev_info_t *dip;
329 9 struct reg *regp;
330 10 ...
331 11 };
332 12
333 13 dev_t dev;
334 14 struct xxstate *xsp;
335 15 ...
336 16 #ifdef DEBUG /* in debugging mode, log function call */
337 17 cmn_err(CE_CONT, "!%s%d: xxopen function called.",
338 18 ddi_binding_name(xsp->dip), getminor(dev));
339 19 #endif /* end DEBUG */
340 20 ...
341 21 /* display device power failure on system console */
342 22 if ((xsp->regp->csr & POWER) == OFF)
343 23 cmn_err(CE_NOTE, "^OFF.",
344 24 ddi_binding_name(xsp->dip), getminor(dev));
345 25 ...
346 26 /* display warning if device has bad VTOC */
347 27 if (xsp->regp->csr & BADVTOC)
348 28 cmn_err(CE_WARN, "%s%d: xxopen: Bad VTOC.",
349 29 ddi_binding_name(xsp->dip), getminor(dev));
350 .Ed
351 .It Sy Example 2 No Using the %b conversion specification
352 This example shows how to use the
353 .Sy %b
354 conversion specification.
355 Because of the leading
356 .Qq Sy \?
357 character in the format string, this message will always be logged, but it will
358 only be displayed when the kernel is booted in verbose mode.
359 .Bd -literal
360 cmn_err(CE_CONT, "?reg=0x%b\en", regval, "\e020\e3Intr\e2Err\e1Enable");
361 .Ed
362 .It Sy Example 3 No Using Fa regval
363 When
364 .Fa regval
365 is set to
366 .Pq decimal
367 13, the following message would be displayed:
368 .Bd -literal
369 reg=0xd<Intr,,Enable>
370 .Ed
371 .It Sy Example 4 No Error Routine
372 This example shows an error reporting routine which accepts a variable number
373 of arguments and displays a single line error message both in the system log
374 and on the system console.
375 Note the use of
376 .Fn vsprintf
377 to construct the error message before calling
378 .Fn cmn_err .
379 .Bd -literal
380 #include <sys/varargs.h>
381 #include <sys/ddi.h>
382 #include <sys/sunddi.h>
383 #define MAX_MSG 256;
385 void
386 xxerror(dev_info_t *dip, int level, const char *fmt, ...)
387 {
388 va_list ap;
389 int instance;
390 char buf[MAX_MSG], *name;
392 instance = ddi_get_instance(dip);
393 name = ddi_binding_name(dip);
395 /* format buf using fmt and arguments contained in ap */
397 va_start(ap, fmt);
398 vsprintf(buf, fmt, ap);
399 va_end(ap);
401 /* pass formatted string to cmn_err(9F) */
403 cmn_err(level, "%s%d: %s", name, instance, buf);
405 }
406 .Ed
407 .It Sy Example 5 No Log to Current Zone
408 This example shows how messages can be sent to the log of the zone in which a
409 thread is currently running, when applicable.
410 Note that most hardware-related messages should instead be sent to the global
411 zone using
412 .Fn cmn_err .
413 .Bd -literal
414 zcmn_err(crgetzoneid(ddi_get_cred()), CE_NOTE, "out of processes");
415 .Ed
416 .El
417 .Sh SEE ALSO
418 .Xr dmesg 1M ,
419 .Xr kernel 1M ,
420 .Xr zones 5 ,
421 .Xr ddi_binding_name 9F ,
422 .Xr ddi_cred 9F ,
423 .Xr ddi_driver_name 9F ,
424 .Xr ddi_get_instance 9F ,
425 .Xr sprintf 9F ,
426 .Xr va_arg 9F ,
427 .Xr va_end 9F ,
428 .Xr va_start 9F
429 .Pp
430 Writing Device Drivers
431 .Sh WARNINGS
432 The
433 .Fn cmn_err
434 function with the
435 .Sy CE_CONT
436 argument can be used by driver developers as a driver code debugging tool.
437 However, using
438 .Fn cmn_err
439 in this capacity can change system timing characteristics.
440 .Sh NOTES
441 Messages of arbitrary length can be generated using
442 .Fn cmn_err ,
443 but if the call to
444 .Fn cmn_err
445 is made from high-level interrupt context and insufficient memory is available
446 to create a buffer of the specified size, the message will be truncated to
447 LOG_MSGSIZE
448 bytes
449 .Pq see Pa sys/log.h .
450 For this reason, callers of
451 .Fn cmn_err
452 that require complete and accurate message generation should post down from
453 high-level interrupt context before calling
454 .Fn cmn_err .