cmn_err(D3)cmn_err(D3)NAMEcmn_err - display an error message or panic the system
SYNOPSIS
#include <sys/cmn_err.h>
#include <sys/ddi.h>
void cmn_err(int level, char *format, ... /* args */);
void cmn_err_tag(int seqnumber,int level, char *format, ... /* args */);
#include <stdarg.h>
void icmn_err(int level, char *format, va_list ap);
Arguments
seqnumber
Unique sequence number for tracking particular message through
Embedded Support Partner (ESP) subsystem.
level
Indicates the severity of the error condition.
format
The message to be displayed.
args The set of arguments passed with the message being displayed.
ap An argument list of type va_list, as documented in stdarg(5).
DESCRIPTION
These functions display a message on the console and/or store it in the
kernel buffer putbuf. They can also initiate a system panic. In addition
to above functionality cmn_err_tag allows to detect and identify message
using unique ESP sequence number. It can also activate different user
defined actions through ESP.
Return Values
None
USAGE
seqnumber Argument
The unique sequence number is used for tracking the particular message in
the Embedded Support Partner environment. For more details see esp(1).
level Argument
Valid values for level are:
CE_CONT
Used to continue a previous message or to display an
informative message not connected with an error.
Page 1
cmn_err(D3)cmn_err(D3)
CE_DEBUG
Used to display an informative message which is generally
expected to be of use only when debugging the associated
code.
CE_NOTE
Used to display a message preceded with ``NOTICE: .'' This
message is used to report system events that do not
necessarily require action, but may interest the system
administrator. For example, a message saying that a sector
on a disk needs to be accessed repeatedly before it can be
accessed correctly might be noteworthy.
CE_WARN
Used to display a message preceded with ``WARNING: .'' This
message is used to report system events that require
attention, such as those where if an action is not taken, the
system may panic or provide reduced functionality.
Generally, WARNINGs are associated with situations that are
less severe than ALERTs. For example, when a peripheral
device does not initialize correctly, this level might be
used.
CE_ALERT
Used to display a message preceded with ``ALERT: .'' This
message is used to report system events that require
immediate attention, such as those where if an action is not
taken, the system may panic or provide reduced functionality.
Generally, ALERTs are associated with situations that are
more severe than WARNINGs. For example, when a networking
device loses its carrier, this level might be used.
CE_PANIC
Used to display a message preceded with ``PANIC: ,'' and
panic the system. Drivers should use this level only for
debugging or in the case of severe errors that indicate that
the system cannot continue to function. This level halts
processing.
format Argument
The format is a character string giving a message pattern in a style
similar to that of f4printf(3S).
By default, the message is sent both to the system console and to the
circular kernel buffer putbuf. When the first character in format is a
circumflex (``^''), the message goes only to the console. When the first
character in format is an exclamation point (``!''), the message goes
only to putbuf.
The size of the kernel buffer putbuf is defined by the kernel variable
putbufsz. Driver developers or administrators can display the putbuf
buffer using appropriate debugging or administrative tools such as
Page 2
cmn_err(D3)cmn_err(D3)idbg(1M).
cmn_err appends \n to each format string, even when a message is
sent to putbuf, except when level is CE_CONT.
Valid conversion specifications are %s, %u, %d, %o, and %x. The
cmn_err function is otherwise similar to the printf(3S) library
subroutine in its interpretation of the format string, except that
cmn_err does not accept length specifications in conversion
specifications. For example, %3d is invalid and will be treated as
a literal string, resulting in a mismatch of arguments.
args Argument
Any argument within the range of supported conversion specifications can
be passed.
ap Argument
The icmn_err function is functionally the same as cmn_err except that it
takes a variable argument list as prepared by the stdarg(5) macros. This
allows the driver developer to create debugging functions that take
arguments similar to those of cmn_err, but that add extra features or
perform conditional actions.
General Considerations
At times, a driver may encounter error conditions requiring the attention
of a system console monitor. These conditions may mean halting the
system; however, this must be done with caution. Except during the
debugging stage, or in the case of a serious, unrecoverable error, a
driver should never stop the system.
The cmn_err function with the CE_CONT argument can be used by driver
developers as a driver code debugging tool. However, using cmn_err in
this capacity can change system timing characteristics.
Level
Initialization, Base or Interrupt.
Synchronization Constraints
Does not sleep.
If level is CE_PANIC, then driver-defined basic locks, read/write locks,
and sleep locks may not be held across calls to this function. For other
levels, locks may be held.
Examples
The cmn_err function can record tracing and debugging information only in
the putbuf buffer (lines 12 and 13) or display problems with a device
only on the system console (lines 17 and 18). The cmn_err_tag function
allows to trace particular error event (lines 24 and 25) through Embedded
Page 3
cmn_err(D3)cmn_err(D3)
Support Partner subsystem.
1 struct device { /* device registers layout */
...
2 int status; /* device status word */
3 };
4 extern struct device xx_dev[]; /* physical device registers */
5 extern int xx_cnt; /* number of physical devices */
...
6 int
7 xxopen(dev_t *devp, int flag, int otyp, cred_t *crp)
8 {
9 struct device *dp;
10 dp = xx_dev[getminor(*devp)]; /* get dev registers */
11 #ifdef DEBUG /* in debugging mode, log function call */
12 cmn_err(CE_DEBUG, "!xxopen function call, dev = 0x%x", *devp);
13 cmn_err(CE_CONT, "! flag = 0x%x", flag);
14 #endif
15 /* display device power failure on system console */
16 if ((dp->status & POWER) == OFF)
17 cmn_err(CE_WARN, "^xxopen: Power is OFF on device %d port %d",
18 getemajor(*devp), geteminor(*devp));
19
20 /* fix device low power level through ESP subsystem */
21 /* It can activate some actions like send email, show popup */
22 /* window and others for this event */
23 if ((dp->status & POWER) == LOW)
24 cmn_err_tag(0x58735, "xxopen: Power is LOW on device %d port %d",
25 getemajor(*devp), geteminor(*devp));
REFERENCESprintf(3S), stdarg(5), print(D2), esp(1).
Page 4
