1cmn_err(9F) Kernel Functions for Drivers cmn_err(9F)
2
6 cmn_err, vcmn_err, zcmn_err - display an error message or panic the
7 system
8
10 #include <sys/cmn_err.h>
11 #include <sys/ddi.h>
12 #include <sys/sunddi.h>
13 void cmn_err(int level, char *format...
17 #include <sys/varargs.h>
20 void vcmn_err(int level, char *format, va_list ap);
24 #include <sys/types.h>
27 void zcmn_err(zoneid_t zoneid, int level, char *format...);
31
34 Architecture independent level 1 (DDI/DKI).
35
37 cmn_err()
38 level A constant indicating the severity of the error condition.
39 format Message to be displayed.
42 vcmn_err()
45 The vcmn_err() function takes level and format as described for
46 cmn_err(), but its third argument is different:
47 ap Variable argument list passed to the function.
49 zcmn_err()
52 The zcmn_err() function works exactly like cmn_err(), but includes an
53 additional argument:
54 zoneid Zone to which log messages should be directed. See zones(5).
56
59 cmn_err()
60 The cmn_err() function displays a specified message on the console.
61 cmn_err() can also panic the system. When the system panics, it
62 attempts to save recent changes to data, display a "panic message" on
63 the console, attempt to write a core file, and halt system processing.
64 See the CE_PANIC level below.
65 level is a constant indicating the severity of the error condition. The
68 four severity levels are:
69 CE_CONT Used to continue another message or to display an informa‐
71 tive message not associated with an error. Note that multi‐
72 ple CE_CONT messages without a newline may or may not
73 appear on the system console or in the system log as a sin‐
74 gle line message. A single line message may be produced by
75 constructing the message with sprintf(9F) or vsprintf(9F)
76 before calling cmn_err().
77 CE_NOTE Used to display a message preceded with NOTICE. This mes‐
80 sage is used to report system events that do not necessar‐
81 ily require user action, but may interest the system admin‐
82 istrator. For example, a message saying that a sector on a
83 disk needs to be accessed repeatedly before it can be
84 accessed correctly might be noteworthy.
85 CE_WARN Used to display a message preceded with WARNING. This mes‐
88 sage is used to report system events that require immediate
89 attention, such as those where if an action is not taken,
90 the system may panic. For example, when a peripheral device
91 does not initialize correctly, this level should be used.
92 CE_PANIC Used to display a message preceded with "panic", and to
95 panic the system. Drivers should specify this level only
96 under the most severe conditions or when debugging a
97 driver. A valid use of this level is when the system cannot
98 continue to function. If the error is recoverable, or not
99 essential to continued system operation, do not panic the
100 system.
101 format is the message to be displayed. It is a character string which
105 may contain plain characters and conversion specifications. By default,
106 the message is sent both to the system console and to the system log.
107 Each conversion specification in format is introduced by the % charac‐
110 ter, after which the following appear in sequence:
111 An optional decimal digit specifying a minimum field width for numeric
114 conversion. The converted value will be right-justified and padded with
115 leading zeroes if it has fewer characters than the minimum.
116 An optional l (ll) specifying that a following d, D, o, O, x, X, or u
119 conversion character applies to a long (long long) integer argument. An
120 l (ll) before any other conversion character is ignored.
121 A character indicating the type of conversion to be applied:
124 d,D,o,O,x,X,u The integer argument is converted to signed decimal
126 (d, D), unsigned octal (o, O), unsigned hexadecimal
127 (x, X), or unsigned decimal (u), respectively, and
128 displayed. The letters abcdef are used for x and X
129 conversion.
130 c The character value of the argument is displayed.
133 b The %b conversion specification allows bit values to
136 be displayed meaningfully. Each %b takes an integer
137 value and a format string from the argument list. The
138 first character of the format string should be the
139 output base encoded as a control character. This base
140 is used to display the integer argument. The remaining
141 groups of characters in the format string consist of a
142 bit number (between 1 and 32, also encoded as a con‐
143 trol character) and the next characters (up to the
144 next control character or '\0') give the name of the
145 bit field. The string corresponding to the bit fields
146 set in the integer argument is displayed after the
147 numerical value. See EXAMPLE section.
148 p The argument is taken to be a pointer; the value of
151 the pointer is displayed in unsigned hexadecimal. The
152 display format is equivalent to %lx. To avoid lint
153 warnings, cast pointers to type void * when using the
154 %p format specifier.
155 s The argument is taken to be a string (character
158 pointer), and characters from the string are displayed
159 until a null character is encountered. If the charac‐
160 ter pointer is NULL, the string <null string> is used
161 in its place.
162 % Copy a %; no argument is converted.
165 The first character in format affects where the message will be writ‐
169 ten:
170 ! The message goes only to the system log.
172 ^ The message goes only to the console.
175 ? If level is also CE_CONT, the message is always sent to the system
178 log, but is only written to the console when the system has been
179 booted in verbose mode. See kernel(1M). If neither condition is
180 met, the '?' character has no effect and is simply ignored.
181 Refer to syslogd(1M) to determine where the system log is written.
185 The cmn_err() function sends log messages to the log of the global
188 zone. cmn_err() appends a \n to each format, except when level is
189 CE_CONT.
190 vcmn_err()
192 The vcmn_err() function is identical to cmn_err() except that its last
193 argument, ap, is a pointer to a variable list of arguments. ap contains
194 the list of arguments used by the conversion specifications in format.
195 ap must be initialized by calling va_start(9F). va_end(9F) is used to
196 clean up and must be called after each traversal of the list. Multiple
197 traversals of the argument list, each bracketed by va_start(9F) and
198 va_end(9F), are possible.
199 zcmn_err()
201 With the exception of its first argument (zoneid), zcmn_err() is iden‐
202 tical to cmn_err(). zoneid is the numeric ID of the zone to which the
203 message should be directed. Note that zoneid only has an effect if the
204 message is sent to the system log. Using zoneid will cause messages to
205 be sent to the log associated with the specified local zone rather than
206 the log in the global zone. This is accomplished by the message being
207 received and processed by the syslogd(1M) process running in the speci‐
208 fied zone instead of the one running in the global zone. You can
209 retrieve a process zone ID from its credential structure using crget‐
210 zoneid(9F).
211
213 None. However, if an unknown level is passed to cmn_err(), the follow‐
214 ing panic error message is displayed:
215 panic: unknown level in cmn_err (level=level, msg=format)
217
221 The cmn_err() function can be called from user, kernel, interrupt, or
222 high-level interrupt context.
223
225 Example 1 Using cmn_err()
226 This first example shows how cmn_err() can record tracing and debugging
229 information only in the system log (lines 17); display problems with a
230 device only on the system console (line 23); or display problems with
231 the device on both the system console and in the system log (line 28).
232 1 struct reg {
235 2 uchar_t data;
236 3 uchar_t csr;
237 4 };
238 5
239 6 struct xxstate {
240 7 ...
241 8 dev_info_t *dip;
242 9 struct reg *regp;
243 10 ...
244 11 };
245 12
246 13 dev_t dev;
247 14 struct xxstate *xsp;
248 15 ...
249 16 #ifdef DEBUG /* in debugging mode, log function call */
250 17 cmn_err(CE_CONT, "!%s%d: xxopen function called.",
251 18 ddi_binding_name(xsp->dip), getminor(dev));
252 19 #endif /* end DEBUG */
253 20 ...
254 21 /* display device power failure on system console */
255 22 if ((xsp->regp->csr & POWER) == OFF)
256 23 cmn_err(CE_NOTE, "^OFF.",
257 24 ddi_binding_name(xsp->dip), getminor(dev));
258 25 ...
259 26 /* display warning if device has bad VTOC */
260 27 if (xsp->regp->csr & BADVTOC)
261 28 cmn_err(CE_WARN, "%s%d: xxopen: Bad VTOC.",
262 29 ddi_binding_name(xsp->dip), getminor(dev));
263 Example 2 Using the %b conversion specification
266 This example shows how to use the %b conversion specification. Because
269 of the leading '?' character in the format string, this message will
270 always be logged, but it will only be displayed when the kernel is
271 booted in verbose mode.
272 cmn_err(CE_CONT, "?reg=0x%b\n", regval, "\020\3Intr\2Err\1Enable");
275 Example 3 Using regval
279 When regval is set to (decimal) 13, the following message would be dis‐
282 played:
283 reg=0xd<Intr,,Enable>
286 Example 4 Error Routine
290 This example shows an error reporting routine which accepts a variable
293 number of arguments and displays a single line error message both in
294 the system log and on the system console. Note the use of vsprintf() to
295 construct the error message before calling cmn_err().
296 #include <sys/varargs.h>
299 #include <sys/ddi.h>
300 #include <sys/sunddi.h>
301 #define MAX_MSG 256;
302 void
304 xxerror(dev_info_t *dip, int level, const char *fmt, ...)
305 {
306 va_list ap;
307 int instance;
308 char buf[MAX_MSG], *name;
309 instance = ddi_get_instance(dip);
311 name = ddi_binding_name(dip);
312 /* format buf using fmt and arguments contained in ap */
314 va_start(ap, fmt);
316 vsprintf(buf, fmt, ap);
317 va_end(ap);
318 /* pass formatted string to cmn_err(9F) */
320 cmn_err(level, "%s%d: %s", name, instance, buf);
322 }
324 Example 5 Log to Current Zone
327 This example shows how messages can be sent to the log of the zone in
330 which a thread is currently running, when applicable. Note that most
331 hardware-related messages should instead be sent to the global zone
332 using cmn_err().
333 zcmn_err(crgetzoneid(ddi_get_cred()), CE_NOTE, "out of processes0);
336
339 dmesg(1M), kernel(1M), printf(3C), zones(5), ddi_binding_name(9F),
340 ddi_cred(9F), sprintf(9F), va_arg(9F), va_end(9F), va_start(9F),
341 vsprintf(9F)
342 Writing Device Drivers
345
347 The cmn_err() function with the CE_CONT argument can be used by driver
348 developers as a driver code debugging tool. However, using cmn_err() in
349 this capacity can change system timing characteristics.
350
352 Messages of arbitrary length can be generated using cmn_err(), but if
353 the call to cmn_err() is made from high-level interrupt context and
354 insufficient memory is available to create a buffer of the specified
355 size, the message will be truncated to LOG_MSGSIZE bytes (see
356 <sys/log.h>). For this reason, callers of cmn_err() that require com‐
357 plete and accurate message generation should post down from high-level
358 interrupt context before calling cmn_err().
359SunOS 5.11 16 Jan 2006 cmn_err(9F)