SVR5
cmn_err(D3)
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 */);
Description
cmn_err( )
displays a specified message on the console
and/or stores it in the kernel putbuf buffer.
cmn_err( )
can also be used to panic the system
although current drivers should not call it for this purpose.
Arguments
level-
Indicates the severity of the error
condition.
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.
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 that might cause the system to panic
if action is not taken.
CE_PANIC-
Used to display a message preceded with PANIC:
and panic the system.
DDI 8 drivers should never call this function;
to call the debugger,
use the
call_demon(D3)
function instead.
Production drivers should never panic the system.
format-
The message to be displayed.
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.
Driver developers or administrators can read
the putbuf buffer using the
crash
command
or the
kdb
or scodb debuggers.
-
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
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-
The set of arguments passed with the message being displayed.
Any argument within the range of supported conversion specifications
can be passed.
Return values
None
Usage
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.
Context and synchronization
All
contexts.
If level is CE_PANIC,
then this function cannot be called
while driver-defined basic locks, read/write locks, and sleep locks
are held.
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));
External dependencies
On SVR5 systems,
cmn_err( )
console output is intercepted by the
syslogd
process.
To make these messages appear on the console
while debugging a driver,
disable the syslogd daemon.
The size of the putbuf kernel buffer
is defined by the kernel variable PUTBUFSZ.
This should be set to the maximum allowable size
when debugging drivers.
Hardware applicability
All
Version applicability
ddi:
1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
Differences between versions
Pre-DDI 8 drivers can use the
CE_PANIC level to the
cmn_err( )
function within debugging loops
to call the debugger,
but production drivers should never panic the system.
Future directions
Support for the CE_PANIC level
will be removed in a future version of the operating system.
The architecture of having syslogd intercept all
cmn_err( )
messages is being studied and may change
in a future release of the operating system.
SCO OpenServer compatibility
The
cmn_err(D3oddi)
function is supported on SCO OpenServer systems
with the following syntactic differences:
-
SCO OpenServer console messages are logged to
the /usr/adm/messages file.
-
The SCO OpenServer version supports an additional
format specifier, !!.
-
The SCO OpenServer
cmn_err( )
function also supports the
%b and %c
data type specifications.
References
cmn_err(D3oddi),
fprintf
``Error notification'' in Developing device drivers
``Coding the driver for debugging'' in Developing device drivers
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005