DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
SCO OpenServer

cmn_err(D3oddi)


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)

 +-----+-----------------------------------------+
 |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.

Context and synchronization

All contexts.

Hardware applicability

All

Version applicability

oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

Differences between versions

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:

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

References

calldebug(D3oddi), crash(ADM), deverr(D3oddi), printcfg(D3oddi), printf(D3oddi)

``Error handling'' in HDK Technical Reference
``Coding the driver for debugging'' in Developing device drivers


19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 5 HDK - June 2005