Kernel Functions for Drivers cmnerr(9F)
NAME
cmnerr, vcmnerr, zcmnerr - display an error message or
panic the system
SYNOPSIS
#include
#include
#include
void cmnerr(int level, char *format...
#include
void vcmnerr(int level, char *format, valist ap);
#include
void zcmnerr(zoneidt zoneid, int level, char *format...);
INTERFACE LEVEL
Architecture independent level 1 (DI/DKI).
PARAMETERS
cmnerr()
level A constant indicating the severity of the error
condition.
format Message to be displayed.
vcmnerr()
The vcmnerr() function takes level and format as described
for cmnerr(), but its third argument is different:
ap Variable argument list passed to the function.
zcmnerr()
The zcmnerr() function works exactly like cmnerr(), but
includes an additional argument:
SunOS 5.11 Last change: 16 Jan 2006 1
Kernel Functions for Drivers cmnerr(9F)
zoneid Zone to which log messages should be directed. See
zones(5).
DESCRIPTION
cmnerr()
The cmnerr() function displays a specified message on the
console. cmnerr() can also panic the system. When the sys-
tem panics, it attempts to save recent changes to data,
display a "panic message" on the console, attempt to write a
core file, and halt system processing. See the CEPANIC
level below.
level is a constant indicating the severity of the error
condition. The four severity levels are:
CECONT Used to continue another message or to display
an informative message not associated with an
error. Note that multiple CECONT messages
without a newline may or may not appear on the
system console or in the system log as a single
line message. A single line message may be pro-
duced by constructing the message with
sprintf(9F) or vsprintf(9F) before calling
cmnerr().
CENOTE 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 exam-
ple, a message saying that a sector on a disk
needs to be accessed repeatedly before it can be
accessed correctly might be noteworthy.
CEWARN 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.
CEPANIC Used to display a message preceded with "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
SunOS 5.11 Last change: 16 Jan 2006 2
Kernel Functions for Drivers cmnerr(9F)
essential to continued system operation, do not
panic the system.
format is the message to be displayed. It is a character
string which may contain plain characters and conversion
specifications. By default, the message is sent both to the
system console and to the system log.
Each conversion specification in format is introduced by the
% character, after which the following appear in sequence:
An optional decimal digit specifying a minimum field width
for numeric conversion. The converted value will be right-
justified and padded with leading zeroes if it has fewer
characters than the minimum.
An optional l (ll) specifying that a following d, D, o, O,
x, X, or u conversion character applies to a long (long
long) integer argument. An l (ll) before any other conver-
sion character is ignored.
A character indicating the type of conversion to be applied:
d,D,o,O,x,X,u The integer argument is converted to signed
decimal (d, D), unsigned octal (o, O),
unsigned hexadecimal (x, X), or unsigned
decimal (u), respectively, and displayed.
The letters abcdef are used for x and X
conversion.
c The character value of the argument is
displayed.
b The %b conversion specification allows bit
values to be displayed 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 char-
acter. This base is used to display 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
SunOS 5.11 Last change: 16 Jan 2006 3
Kernel Functions for Drivers cmnerr(9F)
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
displayed after the numerical value. See
EXAMPLE section.
p The argument is taken to be a pointer; the
value of the pointer is displayed in
unsigned hexadecimal. The display format is
equivalent to %lx. To avoid lint warnings,
cast pointers to type void * when using the
%p format specifier.
s The argument is taken to be a string (char-
acter pointer), and characters from the
string are displayed until a null character
is encountered. If the character pointer is
NUL, the string is used in
its place.
% Copy a %; no argument is converted.
The first character in format affects where the message will
be written:
! The message goes only to the system log.
^ The message goes only to the console.
? If level is also CECONT, the message is always sent to
the system log, 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 '?' char-
acter has no effect and is simply ignored.
Refer to syslogd(1M) to determine where the system log is
written.
The cmnerr() function sends log messages to the log of the
global zone. cmnerr() appends a \n to each format, except
when level is CECONT.
SunOS 5.11 Last change: 16 Jan 2006 4
Kernel Functions for Drivers cmnerr(9F)
vcmnerr()
The vcmnerr() function is identical to cmnerr() except
that its last argument, ap, is a pointer to a variable list
of arguments. ap contains the list of arguments used by the
conversion specifications in format. ap must be initialized
by calling vastart(9F). vaend(9F) is used to clean up and
must be called after each traversal of the list. Multiple
traversals of the argument list, each bracketed by
vastart(9F) and vaend(9F), are possible.
zcmnerr()
With the exception of its first argument (zoneid),
zcmnerr() is identical to cmnerr(). zoneid is the numeric
ID of the zone to which the message should be directed. Note
that zoneid only has an effect if the message is sent to the
system log. Using zoneid will cause messages to be sent to
the log associated with the specified local zone rather than
the log in the global zone. This is accomplished by the mes-
sage being received and processed by the syslogd(1M) process
running in the specified zone instead of the one running in
the global zone. You can retrieve a process zone ID from its
credential structure using crgetzoneid(9F).
RETURN VALUES
None. However, if an unknown level is passed to cmnerr(),
the following panic error message is displayed:
panic: unknown level in cmnerr (level=level, msg=format)
CONTEXT
The cmnerr() function can be called from user, kernel,
interrupt, or high-level interrupt context.
EXAMPLES
Example 1 Using cmnerr()
This first example shows how cmnerr() can record tracing
and debugging information only in the system log (lines 17);
display problems with a device only on the system console
(line 23); or display problems with the device on both the
system console and in the system log (line 28).
1 struct reg {
2 uchart data;
3 uchart csr;
4 };
5
6 struct xxstate {
SunOS 5.11 Last change: 16 Jan 2006 5
Kernel Functions for Drivers cmnerr(9F)
7 ...
8 devinfot *dip;
9 struct reg *regp;
10 ...
11 };
12
13 devt dev;
14 struct xxstate *xsp;
15 ...
16 #ifdef DEBUG /* in debugging mode, log function call */
17 cmnerr(CECONT, "!%s%d: xxopen function called.",
18 ddibindingname(xsp->dip), getminor(dev));
19 #endif /* end DEBUG */
20 ...
21 /* display device power failure on system console */
22 if ((xsp->regp->csr & POWER) == OF)
23 cmnerr(CENOTE, "^OF.",
24 ddibindingname(xsp->dip), getminor(dev));
25 ...
26 /* display warning if device has bad VTOC */
27 if (xsp->regp->csr & BADVTOC)
28 cmnerr(CEWARN, "%s%d: xxopen: Bad VTOC.",
29 ddibindingname(xsp->dip), getminor(dev));
Example 2 Using the %b conversion specification
This example shows how to use the %b conversion specifica-
tion. 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.
cmnerr(CECONT, "?reg=0x%b\n", regval, "\020\3Intr\2Err\1Enable");
Example 3 Using regval
When regval is set to (decimal) 13, the following message
would be displayed:
reg=0xd
Example 4 Error Routine
SunOS 5.11 Last change: 16 Jan 2006 6
Kernel Functions for Drivers cmnerr(9F)
This example shows an error reporting routine which accepts
a variable number of arguments and displays a single line
error message both in the system log and on the system con-
sole. Note the use of vsprintf() to construct the error mes-
sage before calling cmnerr().
#include
#include
#include
#define MAXMSG 256;
void
xxerror(devinfot *dip, int level, const char *fmt, ...)
{
valist ap;
int instance;
char buf[MAXMSG], *name;
instance = ddigetinstance(dip);
name = ddibindingname(dip);
/* format buf using fmt and arguments contained in ap */
vastart(ap, fmt);
vsprintf(buf, fmt, ap);
vaend(ap);
/* pass formatted string to cmnerr(9F) */
cmnerr(level, "%s%d: %s", name, instance, buf);
}
Example 5 Log to Current Zone
This example shows how messages can be sent to the log of
the zone in which a thread is currently running, when appli-
cable. Note that most hardware-related messages should
instead be sent to the global zone using cmnerr().
zcmnerr(crgetzoneid(ddigetcred()), CENOTE, "out of processes0);
SEE ALSO
dmesg(1M), kernel(1M), printf(3C), zones(5),
ddibindingname(9F), ddicred(9F), sprintf(9F), vaarg(9F),
vaend(9F), vastart(9F), vsprintf(9F)
SunOS 5.11 Last change: 16 Jan 2006 7
Kernel Functions for Drivers cmnerr(9F)
Writing Device Drivers
WARNINGS
The cmnerr() function with the CECONT argument can be used
by driver developers as a driver code debugging tool. How-
ever, using cmnerr() in this capacity can change system
timing characteristics.
NOTES
Messages of arbitrary length can be generated using
cmnerr(), but if the call to cmnerr() is made from high-
level interrupt context and insufficient memory is available
to create a buffer of the specified size, the message will
be truncated to LOGMSGSIZE bytes (see ). For
this reason, callers of cmnerr() that require complete and
accurate message generation should post down from high-level
interrupt context before calling cmnerr().
SunOS 5.11 Last change: 16 Jan 2006 8
|
