NAME

cmn_err, vcmn_err - display an error message or panic the system

SYNOPSIS

#include <sys/cmn_err.h>

void cmn_err( int level, char * format, ...);
void vcmn_err( int level, char * format, va_list ap);

ARGUMENTS

cmn_err( )

level

A constant indicating the severity of the error condition. The four severity levels are:

CE_CONT

Used to continue another 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 user 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 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

Used to display a message preceded with PANIC or DOUBLE PANIC, and to panic the system. Drivers should specify this level only under the most severe conditions or when debugging a driver. A valid use of this level is when the system cannot

continue to function. If the error is recoverable, or not essential to continued system operation, do not panic the system. This level halts multiuser processing.

format

The message to be displayed. By default, the message is sent both to the system console and to the system buffer. If the first character in format is an '! ' (exclamation point), the message goes only to the system buffer. If the first character in format is a '^ ' (circumflex), the message goes only to the console. If the first character is a '? ' (question mark), and level is CE_CONT, the message is always sent to the system buffer, but is only written to the console when the system has been booted in verbose mode. See kernel(1M). If neither condition is met, the '? ' character has no effect and is simply ignored. Except for the first character, the rules for format are the same as those for printf(3S) strings. To display the contents of the system buffer, use the dmesg (1M)command.

cmn_err appends a \n to each format, except when level is CE_CONT.

Valid conversion specifications are %s, %u ,%d ,%b ,%o, and %x.

The %b conversion specification allows bit values to be printed meaningfully.

Each %b takes an integer value and a format string from the argument list. The first character of the format string should be the output base encoded as a control character. This base is used to print the integer argument. The remaining groups of characters in the format string consist of a bit number (between 1 and 32, also encoded as a control character) and the next characters (up to the next control character or '\0') give the name of the bit field. The string corresponding to the bit fields set in the integer argument is printed after the numerical value. See the examples below.

cmn_err( ) is otherwise similar to the printf(3S) library subroutine in displaying messages.

vcmn_err( )

vcmn_err( ) takes level and format as described for cmn_err( ), but its third argument is different:

ap

The var arg list passed to the function.

INTERFACE LEVEL

Architecture independent level 1 (DDI/DKI).

DESCRIPTION

cmn_err( )

cmn_err( ) displays a specified message on the console. cmn_err( ) can also panic the system.

At times, a driver may encounter error conditions requiring the attention of a primary or secondary system console monitor. These conditions may mean halting multiuser processing; however, this must be done with caution. Except during the debugging stage, a driver should never stop the system.

cmn_err( ) 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.

If CE_PANIC is set, cmn_err( ) stops the machine.

vcmn_err( )

vcmn_err( ) is identical to cmn_err( ) except that its last argument ap is a pointer to a list of arguments.

RETURN VALUES

None. However, if an unknown level is passed to cmn_err( ), the following panic error message is displayed:

PANIC: unknown level in cmn_err (level= level , msg= format)

CONTEXT

cmn_err( ) can be called from user or interrupt context.

EXAMPLES

This first example shows how cmn_err( ) can record tracing and debugging information only in the system buffer (lines 15 and 16); display problems with a device only on the system console (line 21); or stop the system if a required device malfunctions (line 27).

1 struct device {
2     int   control;
3     int   status;

4     int   error;
5     short   recv_char;
6     short   xmit_char;
7 };
8
9 extern struct device xx_addr[];
10 extern int      xx_cnt;
   . . .
11 register struct device * rp;
12 rp = xx_addr[(getminor(dev) >> 4) & 0xf];   /* get dev registers * /
13
14 #ifdef DEBUG           /* in debugging mode, log function call * /
15    cmn_err(CE_NOTE, "!xx_open function call, dev = 0x%x", dev);
16    cmn_err(CE_CONT, "! flag = 0x%x", flag);      /* continue msg * /
17 #endif /* end DEBUG * /
18
19 /* display device power failure on system console * /
20   if ((rp->status & POWER) == OFF)
21    cmn_err(CE_WARN, "xx_open: Power is OFF on device %d port %d",
22         ((getminor(dev) >> 4) & 0xf), (getminor(dev) & 0xf));
23
24 /* halt system if root device has bad VTOC * /
25   if (rp->error == BADVTOC && dev == rootdev)
26    cmn_err(CE_PANIC, "xx_open: Bad VTOC on root device");

The second example shows how to use the %b conversion specification. Because of the leading '? ' character in the format string, this message will always be logged, but it will only be displayed when the kernel is booted in verbose mode.

        cmn_err(CE_CONT, "?reg=0x%b\n", regval, "\020\3Intr\2Err\1Enable");
When regval is set to (decimal) 13 ,the following message would be printed:
        reg=0xd<Intr,,Enable>

SEE ALSO

dmesg (1M),kernel(1M), printf(3S), print(9E), ddi_report_dev (9F)

Writing Device Drivers

NOTES

cmn_err( ) does not accept length specifications in conversion specifications. For example, %3d is ignored.

BUGS

See chapter 12, "Debugging" in Writing Device Drivers.