.IX \f4cmn_err\fP(D3DK)

NAME

cmn_err − display an error message or panic the system

SYNOPSIS

#include <sys/cmn_err.h>
void
cmn_err( int level, char ∗format, . . . /∗ args ∗/);
 void
vcmn_err( int level, char ∗format, va_list ap);

ARGUMENTS

level level indicates the severity of the error condition.  Valid levels are:

CE_CONT
used to continue a previous message or to display an informative message not connected with an error.

CE_NOTE
.IX \f4cmn_err\fP(D3DK), \f4CE_NOTE\f1
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
.IX \f4cmn_err\fP(D3DK), \f4CE_WARN\f1
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
.IX panic
.IX \f4cmn_err\fP(D3DK), \f4CE_PANIC\f1
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. 

CE_PHASE_START
.IX \f4cmn_err\fP(D3DK), \f4CE_PHASE_START\f1
.IX \f4cmn_err\fP(D3DK), phase delimiter
used to display a message preceeded with PHASE START and a time stamp.  There are no trailing newlines added automatically.  All drivers, that are hardened under the GOLD Boot Time Diagnostic initiative need to adhere to the same verbosity scheme. The first level of that scheme requires to delimit major boot phases by printing time stamped phase delimiter messages to the system console. The CE_PHASE_START level of cmn_err(D3DK) is the designated way of printing the start-of-phase delimiter.  A call to drv_getparm(D3DK) needs to be issued by the drivers in order to sense the current verbosity level.  NOTE: The CE_PHASE_START level of cmn_err(D3DK) shall not be used outside the GOLD Boot Time Diagnostic context. 

CE_PHASE_END
.IX \f4cmn_err\fP(D3DK), \f4CE_PHASE_END\f1
used to display a message followed by PHASE END and a time stamp.  There are no trailing newlines added automatically.  The CE_PHASE_END level of cmn_err(D3DK) is the designated way of printing the end-of-phase delimiter required by GOLD Boot Time Diagnostic.  NOTE: The CE_PHASE_END level of cmn_err(D3DK) shall not be used outside of the GOLD Boot Time Diagnostic context. 

CE_NOLOG
.IX \f4cmn_err\fP(D3DK), \f4CE_NOLOG\f1
used to disable the sending of messages to the STREAMS console logger. This flag is used in combination with the above 6 levels but not by itself.

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.  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 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 the set of arguments passed with the message being displayed.  Any argument within the range of supported conversion specifications can be passed. 

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.  /P vcmn_err is the same as cmn_err, except that instead of being called with a variable number of arguments, it is called with an argument list as defined by varargs(5). 

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. 

RETURN VALUE

.IX panic
None.

LEVEL

Base or Interrupt. 

NOTES

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. 

SEE ALSO

print(D2DK) crash(1M) in the System Administrator’s Reference Manual printf(3S) in the Programmer’s Reference Manual

EXAMPLE

.IX \f4cmn_err\fP(D3DK), example
.IX \f4getminor\fP(D3DK), example
.IX panic

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  {
 9register struct device ∗dp;
 10dp = xx_dev[getminor(∗devp)];/∗ get dev registers ∗/
11  #ifdef DEBUG/∗ in debugging mode, log function call ∗/
12cmn_err(CE_NOTE, "!xxopen function call, dev = 0x%x", ∗devp);
13cmn_err(CE_CONT, "! flag = 0x%x", flag);
14  #endif
 15/∗ display device power failure on system console ∗/
16if ((dp->status & POWER) == OFF)
17cmn_err(CE_WARN, "^xxopen: Power is OFF on device %d port %d",
18   getemajor(∗devp), geteminor(∗devp));

DDI/DKI