1cmn_err(9F)              Kernel Functions for Drivers              cmn_err(9F)
2
3
4

NAME

6       cmn_err,  vcmn_err,  zcmn_err  -  display an error message or panic the
7       system
8

SYNOPSIS

10       #include <sys/cmn_err.h>
11       #include <sys/ddi.h>
12       #include <sys/sunddi.h>
13
14
15
16       void cmn_err(int level, char *format...
17
18
19       #include <sys/varargs.h>
20
21
22
23       void vcmn_err(int level, char *format, va_list ap);
24
25
26       #include <sys/types.h>
27
28
29
30       void zcmn_err(zoneid_t zoneid, int level, char *format...);
31
32

INTERFACE LEVEL

34       Architecture independent level 1 (DDI/DKI).
35

PARAMETERS

37   cmn_err()
38       level     A constant indicating the severity of the error condition.
39
40
41       format    Message to be displayed.
42
43
44   vcmn_err()
45       The vcmn_err()  function  takes  level  and  format  as  described  for
46       cmn_err(), but its third argument is different:
47
48       ap    Variable argument list passed to the function.
49
50
51   zcmn_err()
52       The  zcmn_err()  function works exactly like cmn_err(), but includes an
53       additional argument:
54
55       zoneid    Zone to which log messages should be directed. See zones(5).
56
57

DESCRIPTION

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
66
67       level is a constant indicating the severity of the error condition. The
68       four severity levels are:
69
70       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
78
79       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
86
87       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
93
94       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
102
103
104       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
108
109       Each conversion specification in format is introduced by the %  charac‐
110       ter, after which the following appear in sequence:
111
112
113       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
117
118       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
122
123       A character indicating the type of conversion to be applied:
124
125       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
131
132       c                The character value of the argument is displayed.
133
134
135       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
149
150       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
156
157       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
163
164       %                Copy a %; no argument is converted.
165
166
167
168       The  first  character in format affects where the message will be writ‐
169       ten:
170
171       !    The message goes only to the system log.
172
173
174       ^    The message goes only to the console.
175
176
177       ?    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
182
183
184       Refer to syslogd(1M) to determine where the system log is written.
185
186
187       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
191   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
200   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

RETURN VALUES

213       None. However, if an unknown level is passed to cmn_err(), the  follow‐
214       ing panic error message is displayed:
215
216         panic: unknown level in cmn_err (level=level, msg=format)
217
218
219

CONTEXT

221       The  cmn_err()  function can be called from user, kernel, interrupt, or
222       high-level interrupt context.
223

EXAMPLES

225       Example 1 Using cmn_err()
226
227
228       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
233
234         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
264
265       Example 2 Using the %b conversion specification
266
267
268       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
273
274         cmn_err(CE_CONT, "?reg=0x%b\n", regval, "\020\3Intr\2Err\1Enable");
275
276
277
278       Example 3 Using regval
279
280
281       When regval is set to (decimal) 13, the following message would be dis‐
282       played:
283
284
285         reg=0xd<Intr,,Enable>
286
287
288
289       Example 4 Error Routine
290
291
292       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
297
298         #include <sys/varargs.h>
299         #include <sys/ddi.h>
300         #include <sys/sunddi.h>
301         #define MAX_MSG 256;
302
303         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
310         instance = ddi_get_instance(dip);
311         name = ddi_binding_name(dip);
312
313         /* format buf using fmt and arguments contained in ap */
314
315         va_start(ap, fmt);
316         vsprintf(buf, fmt, ap);
317         va_end(ap);
318
319         /* pass formatted string to cmn_err(9F) */
320
321         cmn_err(level, "%s%d: %s", name, instance, buf);
322
323         }
324
325
326       Example 5 Log to Current Zone
327
328
329       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
334
335         zcmn_err(crgetzoneid(ddi_get_cred()), CE_NOTE, "out of processes0);
336
337

SEE ALSO

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
343
344       Writing Device Drivers
345

WARNINGS

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

NOTES

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().
359
360
361
362SunOS 5.11                        16 Jan 2006                      cmn_err(9F)
Impressum