cmn_err(D3) cmn_err(D3)
NAME
cmn_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 */);
Arguments
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.
DESCRIPTION
cmn_err displays a specified message on the console and/or
stores it in the kernel buffer putbuf. cmn_err can also panic
the system.
Return Values
None
USAGE
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.
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.
Copyright 1994 Novell, Inc. Page 1
cmn_err(D3) cmn_err(D3)
CE_WARN
Used to display a message preceded with
``WARNING: .'' 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. For example, when a
peripheral device does not initialize correctly,
this level should 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
By default, the message is sent both to the system console and
to the circular kernel buffer putbuf. If the first character
in format is an exclamation point (``!''), the message goes
only to putbuf. If the first character in format is a
circumflex (``^''), the message goes only to the console. The
size of the kernel buffer putbuf is defined by the kernel
variable putbufsz. Driver developers or administrators can
read the putbuf buffer using appropriate debugging or
administrative tools [for example, crash(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
fprintf(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.
General Considerations
At times, a driver may encounter error conditions requiring
the attention of a system console monitor. These conditions
Copyright 1994 Novell, Inc. Page 2
cmn_err(D3) cmn_err(D3)
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).
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_NOTE, "!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));
Copyright 1994 Novell, Inc. Page 3
cmn_err(D3) cmn_err(D3)
REFERENCES
fprintf(3S)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 4