'\"macro stdmacro
.if n .pH ddi_dki.cmn_err @(#)cmn_err	40.11 of 10/10/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} cmn_err D3DK "" "DDI/DKI" "\&"
.if \nX=1 .ds x} cmn_err D3DK "" "DDI/DKI"
.if \nX=2 .ds x} cmn_err D3DK "" "\&"
.if \nX=3 .ds x} cmn_err "" "" "\&"
.TH \*(x}
.IX "\f4cmn_err\fP(D3DK)"
.SH NAME
\f4cmn_err\f1 \- display an error message or panic the system
.SH SYNOPSIS
.nf
.na
\f4#include <sys/cmn_err.h>
.sp 0.5
int cmn_err( int \f2level, \f4char *\f1\f2format, \f4int\f1 \f2args\f4);\f1
.ad
.fi
.SH ARGUMENTS
.RS 0n 10
.IP "\f2level\f1" 10n
A constant defined in the \f4sys/cmn_err.h\f1 header file.
\f2level\f1 indicates the severity of the error
condition.
The four severity levels are
.RS 12n
.TP 12n
\f4CE_CONT\f1
used to continue another
message or to display an informative message not connected with an error.
.TP
\f4CE_NOTE\f1
used to display a message preceded with \f4NOTICE\f1.  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.
.TP
\f4CE_WARN\f1
used to display a message preceded with \f4WARNING\f1.  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.
.TP
\f4CE_PANIC\f1
.IX panic
used to display a message preceded with \f4PANIC\f1 or \f4DOUBLE
PANIC\f1, 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.
.RE
.IP "\f2format\f1" 10n
The message to be displayed.
By default, the message is sent both to the system console and to the
kernel buffer \f4putbuf\f1.
If the first character in \f2format\f1 is an exclamation point (``\f4!\f1''),
the message goes only to \f4putbuf\f1.
If the first character in \f2format\f1 is a circumflex (``\f4^\f1''),
the message goes only to the console.
Except for the first character,
the rules for \f2format\f1 are the same as those for \f4printf\f1(3S) strings.
To read \f4putbuf\f1, use the following \f4crash\f1(1M) commands:
.P
.RS 16
.nf
\f4od -d putbufsz\f1
\f4od -a putbuf \f2size\f1
.fi
.RE
.IP "" 10n
The first command returns the size of \f4putbuf\f1 (the default is 2000 bytes).
The second command uses the returned \f2size\f1 to read \f4putbuf\f1.
.IP
\f4cmn_err\f1 appends \f4\\n\f1 to each \f2format\f1,
even when a message is sent to \f4putbuf\f1,
except when \f2level\f1 is \f4CE_CONT\f1.
.P
Vaild conversion specifications are %\f4s\f1, %\f4u\f1, %\f4d\f1,
%\f4o\f1, and %\f4x\f1.  The \f4cmn_err\f1 function is otherwise
similar to the \f4printf\f1(3S) library subroutine in displaying
messages on the system console or storing on \f4putbuf\f1.
.P
\f3NOTE:\f1 \f4cmn_err\f1 does not accept length specifications in
conversion specifications.  For example, %\f43d\f1 is ignored. 
.IP "\f2args\f1" 10n
the set of arguments passed with the message being displayed.  Any
argument within the range of supported conversion specifications can
be passed.
.RE
.SH DESCRIPTION
\f4cmn_err\f1 displays a specified message on the console and/or stores it in
the \f4putbuf\f1 array.  \f4cmn_err\f1 can also panic the system.
.P
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.
.P
The \f4cmn_err\f1 function with the \f4CE_CONT\f1 argument can be used by
driver developers as a driver code debugging tool.  However, using
\f4cmn_err\f1 in this capacity can change system timing characteristics.
.P
If \f4CE_PANIC\f1 is set, \f4cmn_err\f1 stops the machine.
.SH RETURN VALUE
.IX panic
None.  However, if an unknown \f2level\f1 is passed to
\f4cmn_err\f1, the following panic error message is displayed:
.P
.RS
\f4PANIC: unknown level in cmn_err (level=\f2level\f4, msg=\f2format\f4)\f1
.RE
.SH LEVEL
Base or Interrupt
.SH SEE ALSO
\f2BCI Driver Development Guide\f1,
Chapter 12
.P
.na
\f4print\f1(D2DK),
\f4printf\f1(3S)
.ad
.SH EXAMPLE
.IX "\f4cmn_err\fP(D3DK), example"
.IX "\f4getminor\fP(D3DK), example"
.IX panic
.P
The \f4cmn_err\f1 function can record tracing and debugging
information only in the \f4putbuf\f1 (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).
.ne 4
.P
.nf
.ft 4
.ps 7
 1  struct  device {               /* physical device registers layout */
 2          int      control;          /* physical device control word */  
 3          int      status;            /* physical device status word */
 4          int      error;                 /* error codes from device */
 5          short    recv_char;       /* receive character from device */
 6          short    xmit_char;        /* transmit character to device */
 7  }; /* end device */
 8
 9  extern struct device xx_addr[];       /* physical device registers */
10  extern int           xx_cnt;         /* number of physical devices */
      . . .
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                     /* send message to system console and to putbuf */
26     if (rp->error == BADVTOC  &&  dev == rootdev)
27        cmn_err(CE_PANIC, "xx_open: Bad VTOC on root device");
.ps
.ft 1
.fi
.P
.FG "cmn_err \- display messages"
