DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
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.


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:

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