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