212 lines
7.4 KiB
Plaintext
212 lines
7.4 KiB
Plaintext
.\" Copyright 1992, 1991 UNIX System Laboratories, Inc.
|
|
.TH cmn_err D3
|
|
.SH NAME
|
|
\f4cmn_err\f1 \- display an error message or panic the system
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\f4#include <sys/cmn_err.h>
|
|
#include <sys/ddi.h>
|
|
.sp .8v
|
|
void cmn_err(int \f2level\fP, char *\f2format\fP, ... /* args */);
|
|
void cmn_err_tag(int \f2seqnumber\fP,int \f2level\fP, char *\f2format\fP, ... /* args */);
|
|
.sp .8v
|
|
#include <stdarg.h>
|
|
void icmn_err(int \f2level\fP, char *\f2format\fP, va_list \f2ap\fP);
|
|
\f1
|
|
.fi
|
|
.SS Arguments
|
|
.RS 0
|
|
.TP 0.5i
|
|
\f2seqnumber\f1
|
|
Unique sequence number for tracking particular message through \f2Embedded Support Partner\f1
|
|
(\f2ESP\f1) subsystem.
|
|
.TP
|
|
\f2level\f1
|
|
Indicates the severity of the error
|
|
condition.
|
|
.TP
|
|
\f2format\f1
|
|
The message to be displayed.
|
|
.TP
|
|
\f2args\f1
|
|
The set of arguments passed with the message being displayed.
|
|
.TP
|
|
\f2ap\f1
|
|
An argument list of type va_list, as documented in \f4stdarg\f1(5).
|
|
.RE
|
|
.SH DESCRIPTION
|
|
These functions display a message on the console and/or store it in
|
|
the kernel buffer \f4putbuf\f1.
|
|
They can also initiate a system panic. In addition to above
|
|
functionality \f4cmn_err_tag\f1 allows to detect and identify message using unique
|
|
\f2ESP\f1 sequence number. It can also activate different user defined actions through \f2ESP\f1.
|
|
.SS "Return Values"
|
|
None
|
|
.SH USAGE
|
|
.SS "seqnumber Argument"
|
|
The unique sequence number is used for tracking the particular message in the
|
|
Embedded Support Partner environment. For more details see \f4esp\f1(1).
|
|
.SS "level Argument"
|
|
Valid values for \f2level\fP are:
|
|
.RS
|
|
.TP 0.7i
|
|
\f4CE_CONT\f1
|
|
Used to continue a previous
|
|
message or to display an informative message not connected with an error.
|
|
.TP
|
|
\f4CE_DEBUG\f1
|
|
Used to display an informative message
|
|
which is generally expected to be of use only
|
|
when debugging the associated code.
|
|
.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 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 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.
|
|
.TP
|
|
\f4CE_ALERT\f1
|
|
Used to display a message preceded with ``\f4ALERT: \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 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.
|
|
.TP
|
|
\f4CE_PANIC\f1
|
|
Used to display a message preceded with ``\f4PANIC: \f1,'' 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.
|
|
.RE
|
|
.SS "format Argument"
|
|
The \f2format\f1 is a character string giving a message pattern
|
|
in a style similar to that of f4printf\f1(3S).
|
|
.PP
|
|
By default, the message is sent both to the system console and to the
|
|
circular kernel buffer \f4putbuf\f1.
|
|
When the first character in \f2format\f1 is a
|
|
circumflex (``\f4^\f1''),
|
|
the message goes only to the console.
|
|
When the first character in \f2format\f1 is an
|
|
exclamation point (``\f4!\f1''),
|
|
the message goes only to \f4putbuf\f1.
|
|
.PP
|
|
The size of the kernel buffer \f4putbuf\f1 is defined by the kernel
|
|
variable \f4putbufsz\f1.
|
|
Driver developers or administrators can display
|
|
the \f4putbuf\f1 buffer using
|
|
appropriate debugging or administrative tools such as \f4idbg\fP(1M).
|
|
.RS 0
|
|
.IP
|
|
\f4cmn_err\f1 appends \f4\\n\f1 to each \f2format\f1 string,
|
|
even when a message is sent to \f4putbuf\f1,
|
|
except when \f2level\f1 is \f4CE_CONT\f1.
|
|
.IP
|
|
Valid 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 its interpretation
|
|
of the \f2format\f1 string, except that \f4cmn_err\f1 does not accept length
|
|
specifications in
|
|
conversion specifications.
|
|
For example, %\f43d\f1 is invalid and
|
|
will be treated as a literal string, resulting in a mismatch of arguments.
|
|
.RE
|
|
.SS "args Argument"
|
|
Any argument within the range of supported conversion specifications can
|
|
be passed.
|
|
.SS "ap Argument"
|
|
The \f4icmn_err\f1 function is functionally the same as \f4cmn_err\f1
|
|
except that it takes a variable argument list as prepared by the
|
|
\f4stdarg\f1(5) macros.
|
|
This allows the driver developer to create debugging functions that
|
|
take arguments similar to those of \f4cmn_err\f1, but that add extra features
|
|
or perform conditional actions.
|
|
.SS "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.
|
|
.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.
|
|
.SS Level
|
|
Initialization, Base or Interrupt.
|
|
.SS "Synchronization Constraints"
|
|
Does not sleep.
|
|
.P
|
|
If \f2level\fP is \f4CE_PANIC\fP,
|
|
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.
|
|
.SS Examples
|
|
The \f4cmn_err\f1 function can record tracing and debugging
|
|
information only in the \f4putbuf\f1 buffer (lines 12 and 13) or display
|
|
problems with a device only on the system console (lines 17 and 18).
|
|
The \f4cmn_err_tag\f1 function allows to trace particular error event (lines 24 and 25)
|
|
through \f2Embedded Support Partner\f1 subsystem.
|
|
.ne 4
|
|
.sp .8v
|
|
.nf
|
|
.ft 4
|
|
1 struct device { /* device registers layout */
|
|
...
|
|
2 int status; /* device status word */
|
|
3 };
|
|
.sp .8v
|
|
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;
|
|
.sp .8v
|
|
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
|
|
.sp .8v
|
|
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));
|
|
.ft 1
|
|
.fi
|
|
.SH REFERENCES
|
|
printf(3S),
|
|
stdarg(5),
|
|
print(D2),
|
|
esp(1).
|