cmn_err(D3)
cmn_err - display an error message or panic the system
As shipped in IRIX 6.5.15. Last changed in IRIX 6.5.7.
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 */); void cmn_err_tag(int seqnumber,int level, char *format, ... /* args */); #include <stdarg.h> void icmn_err(int level, char *format, va_list ap); Arguments seqnumber Unique sequence number for tracking particular message through Embedded Support Partner (ESP) subsystem. 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. ap An argument list of type va_list, as documented in stdarg(5). DESCRIPTION These functions display a message on the console and/or store it in the kernel buffer putbuf. They can also initiate a system panic. In addition to above functionality cmn_err_tag allows to detect and identify message using unique ESP sequence number. It can also activate different user defined actions through ESP. Return Values None USAGE seqnumber Argument The unique sequence number is used for tracking the particular message in the Embedded Support Partner environment. For more details see esp(1). 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_DEBUG Used to display an informative message which is generally expected to be of use only when debugging the associated code. 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 attention, such as those where if an action is not taken, the system may panic or provide reduced functionality. Generally, WARNINGs are associated with situations that are less severe than ALERTs. For example, when a peripheral device does not initialize correctly, this level might be used. CE_ALERT Used to display a message preceded with ``ALERT: .'' 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 or provide reduced functionality. Generally, ALERTs are associated with situations that are more severe than WARNINGs. For example, when a networking device loses its carrier, this level might 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 The format is a character string giving a message pattern in a style similar to that of f4printf(3S). By default, the message is sent both to the system console and to the circular kernel buffer putbuf. When the first character in format is a circumflex (``^''), the message goes only to the console. When the first character in format is an exclamation point (``!''), the message goes only to putbuf. The size of the kernel buffer putbuf is defined by the kernel variable putbufsz. Driver developers or administrators can display the putbuf buffer using appropriate debugging or administrative tools such as idbg(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 Argument Any argument within the range of supported conversion specifications can be passed. ap Argument The icmn_err function is functionally the same as cmn_err except that it takes a variable argument list as prepared by the stdarg(5) macros. This allows the driver developer to create debugging functions that take arguments similar to those of cmn_err, but that add extra features or perform conditional actions. General Considerations 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. 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). The cmn_err_tag function allows to trace particular error event (lines 24 and 25) through Embedded Support Partner subsystem. 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_DEBUG, "!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)); 19 20 /* fix device low power level through ESP subsystem */ 21 /* It can activate some actions like send email, show popup */ 22 /* window and others for this event */ 23 if ((dp->status & POWER) == LOW) 24 cmn_err_tag(0x58735, "xxopen: Power is LOW on device %d port %d", 25 getemajor(*devp), geteminor(*devp)); REFERENCES printf(3S), stdarg(5), print(D2), esp(1).