cmn_err --
log and display informational driver messages
Synopsis
#include <sys/cmn_err.h>
int cmn_err(int severity, char format, int arguments);
Description
The
cmn_err( )
function displays a message on the console and/or in the putbuf structure
Arguments
severity
has five different levels for indicating the
severity of the message:
CE_CONF
Displays a configuration message preceded with CONFIG:.
CE_NOTE
Displays a notice message preceded with NOTICE:.
CE_WARN
Displays a warning message preceded with WARNING:.
CE_PANIC
Panics (halts) the system and displays a message
preceded with the PANIC: string.
If a second panic occurs while this panic is being processed,
a ``double panic'' results.
Drivers should never panic the system directly
and so should not use this severity.
Older drivers sometimes used CE_PANIC in debug sections
to force the debugger to be called.
Current drivers should instead call the
calldebug(D3oddi)
function for debugging.
CE_CONT
Continues a previous message or displays a message without a
preceding severity indicator.
A severity level may be
ORed with CO_INDENT to indent the message, and
CO_NONL to prevent the message being concluded with a
newline.
format
formatting string for the message.
The destination of the message is specified by the way
format begins:
!
Writes the message to putbuf
and to the /usr/adm/messages log file,
but does not display it on the console.
!!
Stores the message in putbuf
but does not display it on the console
or log it in /usr/adm/messages.
It is intended for debugging messages
that are used only during code development.
^
Displays the message on the console
but does not store it in putbuf
or log it to the /usr/adm/messages file.
Any other character at the start of format sends the
message to putbuf, the console,
and the /usr/adm/messages log file.
The supported data type specifications are as follows:
Type
Description
%b
two-digit hexadecimal byte
%c
character
%d
signed decimal
%o
unsigned octal
%s
string (character pointer)
%u
unsigned decimal
%x
hexadecimal (prints with leading zeros)
Specifications can be indicated in either uppercase or lowercase.
Field length specifications cannot be used,
but it is possible to specify precision.
For example, ``%.9d'' sets
the minimum number of digits to be printed
for a signed decimal to nine.
Escaped characters such as \n, \t, \033, and so on
are C language features that are supported by the C compiler
and are thus supported for this kernel function.
arguments
specifies a list of optional variables to be
displayed using format.
Return values
cmn_err( )
always returns 0 (zero).
Usage
For production drivers,
cmn_err( )
is primarily used for error messages
about serious problems the driver has encountered;
within debugging sections of code,
it can also be used for informational messages
that help track driver execution.
The message that is displayed should include
the name of the driver
and a clear identification of the affected device.
The first character to the format parameter
determines whether the message is written to
the console, the /usr/adm/messages log file,
the putbuf, or some combination of these.
putbuf is a circular array in memory
that can be accessed from
crash(ADM)
or the scodb kernel debugger.
Note that a background process writes these messages
to the /usr/adm/messages file;
consequently, the final messages written to
the console and the putbuf when the system panics
are not usually logged to this file.
When debugging a driver that uses a large number of
cmn_err( )
messages, you should set
the PUTBUFSZ tunable parameter to 10000,
its maximum allowable size.
The
cmn_err( )
function is not interrupt-driven and therefore
suspends all other system activities while executing.
Large numbers of
cmn_err( )
messages can affect timing on the system.
In ODDI versions prior to version 5
(SCO OpenServer Release 5.0.5),
the message is preceded with a newline (\n)
for all severity levels except CE_CONT.
Older drivers used the
printf(D3oddi)
function instead of
cmn_err( ).
Current drivers should replace all
printf( )
calls with calls to
cmn_err( ).
The same data type specifications are supported
for both functions.
SVR5 compatibility
The
cmn_err( )
function is supported for all DDI versions,
with the following syntactic differences:
cmn_err( )
messages are logged to
the /usr/adm/syslogs and
the /var/adm/log/osmlog files.
The !! destination marker
in the format argument
is not supported on SVR5.
All messages that are written to the console
are also written to the log files.
Examples
During debugging, you can use
cmn_err( )
to display messages on the console as
follows:
#ifdef MY_DEBUG
cmn_err(CE_NOTE," mydv - mydvioctl routine called - device number = %x", device);
cmn_err(CE_CONT," this is not a problem.\n");
#endif
format, int arguments);