'\" te .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH CMN_ERR 9F "Jan 16, 2006" .SH NAME cmn_err, vcmn_err, zcmn_err \- display an error message or panic the system .SH SYNOPSIS .LP .nf #include #include #include \fBvoid\fR \fBcmn_err\fR(\fBint\fR \fIlevel\fR, \fBchar *\fR\fIformat\fR... .fi .LP .nf #include \fBvoid\fR \fBvcmn_err\fR(\fBint\fR \fIlevel\fR, \fBchar *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); .fi .LP .nf #include \fBvoid\fR \fBzcmn_err\fR(\fBzoneid_t\fR \fIzoneid\fR, \fBint\fR \fIlevel\fR, \fBchar *\fR\fIformat\fR...); .fi .SH INTERFACE LEVEL .sp .LP Architecture independent level 1 (DDI/DKI). .SH PARAMETERS .SS "cmn_err(\|)" .sp .ne 2 .na \fB\fIlevel\fR\fR .ad .RS 10n A constant indicating the severity of the error condition. .RE .sp .ne 2 .na \fB\fIformat\fR\fR .ad .RS 10n Message to be displayed. .RE .SS "vcmn_err(\|)" .sp .LP The \fBvcmn_err()\fR function takes \fIlevel\fR and \fIformat\fR as described for \fBcmn_err()\fR, but its third argument is different: .sp .ne 2 .na \fB\fIap\fR\fR .ad .RS 6n Variable argument list passed to the function. .RE .SS "zcmn_err(\|)" .sp .LP The \fBzcmn_err()\fR function works exactly like \fBcmn_err()\fR, but includes an additional argument: .sp .ne 2 .na \fB\fIzoneid\fR\fR .ad .RS 10n Zone to which log messages should be directed. See \fBzones\fR(5). .RE .SH DESCRIPTION .SS "cmn_err(\|)" .sp .LP The \fBcmn_err()\fR function displays a specified message on the console. \fBcmn_err()\fR can also panic the system. When the system 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 \fBCE_PANIC\fR \fIlevel\fR below. .sp .LP \fIlevel\fR is a constant indicating the severity of the error condition. The four severity levels are: .sp .ne 2 .na \fB\fBCE_CONT\fR\fR .ad .RS 12n Used to continue another message or to display an informative message not associated with an error. Note that multiple \fBCE_CONT\fR 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 produced by constructing the message with \fBsprintf\fR(9F) or \fBvsprintf\fR(9F) before calling \fBcmn_err()\fR. .RE .sp .ne 2 .na \fB\fBCE_NOTE\fR\fR .ad .RS 12n Used to display a message preceded with \fBNOTICE\fR. 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. .RE .sp .ne 2 .na \fB\fBCE_WARN\fR\fR .ad .RS 12n Used to display a message preceded with \fBWARNING\fR. 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. .RE .sp .ne 2 .na \fB\fBCE_PANIC\fR\fR .ad .RS 12n Used to display a message preceded with \fB"panic"\fR, 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. .RE .sp .LP \fIformat\fR 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. .sp .LP Each conversion specification in \fIformat\fR is introduced by the \fB%\fR character, after which the following appear in sequence: .sp .LP 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. .sp .LP An optional \fBl\fR (\fBll\fR) specifying that a following \fBd\fR, \fBD\fR, \fBo\fR, \fBO\fR, \fBx\fR, \fBX\fR, or \fBu\fR conversion character applies to a \fBlong\fR (\fBlong long\fR) integer argument. An \fBl\fR (\fBll\fR) before any other conversion character is ignored. .sp .LP A character indicating the type of conversion to be applied: .sp .ne 2 .na \fB\fBd\fR,\fBD\fR,\fBo\fR,\fBO\fR,\fBx\fR,\fBX\fR,\fBu\fR\fR .ad .RS 17n The integer argument is converted to signed decimal (\fBd\fR, \fBD\fR), unsigned octal (\fBo\fR, \fBO\fR), unsigned hexadecimal (\fBx\fR, \fBX\fR), or unsigned decimal (\fBu\fR), respectively, and displayed. The letters \fBabcdef\fR are used for \fBx\fR and \fBX\fR conversion. .RE .sp .ne 2 .na \fB\fBc\fR\fR .ad .RS 17n The character value of the argument is displayed. .RE .sp .ne 2 .na \fB\fBb\fR\fR .ad .RS 17n The \fB%b\fR conversion specification allows bit values to be displayed meaningfully. Each \fB%b\fR 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 character. 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 next characters (up to the next control character or '\e0') 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. .RE .sp .ne 2 .na \fBp\fR .ad .RS 17n The argument is taken to be a pointer; the value of the pointer is displayed in unsigned hexadecimal. The display format is equivalent to \fB%lx\fR. To avoid lint warnings, cast pointers to type \fBvoid *\fR when using the \fB%p\fR format specifier. .RE .sp .ne 2 .na \fB\fBs\fR\fR .ad .RS 17n The argument is taken to be a string (character pointer), and characters from the string are displayed until a null character is encountered. If the character pointer is \fINULL\fR, the string \fB\fR is used in its place. .RE .sp .ne 2 .na \fB\fB%\fR\fR .ad .RS 17n Copy a \fB%\fR; no argument is converted. .RE .sp .LP The first character in \fIformat\fR affects where the message will be written: .sp .ne 2 .na \fB\fB!\fR\fR .ad .RS 5n The message goes only to the system log. .RE .sp .ne 2 .na \fB\fB^\fR\fR .ad .RS 5n The message goes only to the console. .RE .sp .ne 2 .na \fB\fB?\fR\fR .ad .RS 5n If \fIlevel\fR is also \fBCE_CONT,\fR 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 \fBkernel\fR(1M). If neither condition is met, the '?\|' character has no effect and is simply ignored. .RE .sp .LP Refer to \fBsyslogd\fR(1M) to determine where the system log is written. .sp .LP The \fBcmn_err()\fR function sends log messages to the log of the global zone. \fBcmn_err()\fR appends a \fB\en\fR to each \fIformat\fR, except when \fIlevel\fR is \fBCE_CONT\fR. .SS "vcmn_err(\|)" .sp .LP The \fBvcmn_err()\fR function is identical to \fBcmn_err()\fR except that its last argument, \fIap\fR, is a pointer to a variable list of arguments. \fIap\fR contains the list of arguments used by the conversion specifications in \fIformat\fR. \fIap\fR must be initialized by calling \fBva_start\fR(9F). \fBva_end\fR(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 \fBva_start\fR(9F) and \fBva_end\fR(9F), are possible. .SS "zcmn_err(\|)" .sp .LP With the exception of its first argument (\fBzoneid\fR), \fBzcmn_err()\fR is identical to \fBcmn_err()\fR. \fBzoneid\fR is the numeric ID of the zone to which the message should be directed. Note that \fBzoneid\fR only has an effect if the message is sent to the system log. Using \fBzoneid\fR 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 message being received and processed by the \fBsyslogd\fR(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 \fBcrgetzoneid\fR(9F). .SH RETURN VALUES .sp .LP None. However, if an unknown \fIlevel\fR is passed to \fBcmn_err()\fR, the following panic error message is displayed: .sp .in +2 .nf panic: unknown level in cmn_err (level=\fIlevel\fR, msg=format) .fi .in -2 .sp .SH CONTEXT .sp .LP The \fBcmn_err()\fR function can be called from user, kernel, interrupt, or high-level interrupt context. .SH EXAMPLES .LP \fBExample 1 \fRUsing \fBcmn_err()\fR .sp .LP This first example shows how \fBcmn_err()\fR 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). .sp .in +2 .nf 1 struct reg { 2 uchar_t data; 3 uchar_t csr; 4 }; 5 6 struct xxstate { 7 .\|.\|. 8 dev_info_t *dip; 9 struct reg *regp; 10 .\|.\|. 11 }; 12 13 dev_t dev; 14 struct xxstate *xsp; 15 .\|.\|. 16 #ifdef DEBUG /* in debugging mode, log function call */ 17 cmn_err(CE_CONT, "!%s%d: xxopen function called.", 18 ddi_binding_name(xsp->dip), getminor(dev)); 19 #endif /* end DEBUG */ 20 .\|.\|. 21 /* display device power failure on system console */ 22 if ((xsp->regp->csr & POWER) == OFF) 23 cmn_err(CE_NOTE, "^OFF.", 24 ddi_binding_name(xsp->dip), getminor(dev)); 25 .\|.\|. 26 /* display warning if device has bad VTOC */ 27 if (xsp->regp->csr & BADVTOC) 28 cmn_err(CE_WARN, "%s%d: xxopen: Bad VTOC.", 29 ddi_binding_name(xsp->dip), getminor(dev)); .fi .in -2 .LP \fBExample 2 \fRUsing the %b conversion specification .sp .LP This example shows how to use the \fB%b\fR conversion specification. 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. .sp .in +2 .nf cmn_err(CE_CONT, "?reg=0x%b\en", regval, "\e020\e3Intr\e2Err\e1Enable"); .fi .in -2 .sp .LP \fBExample 3 \fRUsing \fIregval\fR .sp .LP When \fIregval\fR is set to (decimal) \fB13\fR, the following message would be displayed: .sp .in +2 .nf reg=0xd .fi .in -2 .sp .LP \fBExample 4 \fRError Routine .sp .LP 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 console. Note the use of \fBvsprintf()\fR to construct the error message before calling \fBcmn_err()\fR. .sp .in +2 .nf #include #include #include #define MAX_MSG 256; void xxerror(dev_info_t *dip, int level, const char *fmt, .\|.\|.\|) { va_list ap; int instance; char buf[MAX_MSG], *name; instance = ddi_get_instance(dip); name = ddi_binding_name(dip); /* format buf using fmt and arguments contained in ap */ va_start(ap, fmt); vsprintf(buf, fmt, ap); va_end(ap); /* pass formatted string to cmn_err(9F) */ cmn_err(level, "%s%d: %s", name, instance, buf); } .fi .in -2 .LP \fBExample 5 \fRLog to Current Zone .sp .LP This example shows how messages can be sent to the log of the zone in which a thread is currently running, when applicable. Note that most hardware-related messages should instead be sent to the global zone using \fBcmn_err()\fR. .sp .in +2 .nf zcmn_err(crgetzoneid(ddi_get_cred()), CE_NOTE, "out of processes0); .fi .in -2 .SH SEE ALSO .sp .LP \fBdmesg\fR(1M), \fBkernel\fR(1M), \fBprintf\fR(3C), \fBzones\fR(5), \fBddi_binding_name\fR(9F), \fBddi_cred\fR(9F), \fBsprintf\fR(9F), \fBva_arg\fR(9F), \fBva_end\fR(9F), \fBva_start\fR(9F), \fBvsprintf\fR(9F) .sp .LP \fIWriting Device Drivers\fR .SH WARNINGS .sp .LP The \fBcmn_err()\fR function with the \fBCE_CONT\fR argument can be used by driver developers as a driver code debugging tool. However, using \fBcmn_err()\fR in this capacity can change system timing characteristics. .SH NOTES .sp .LP Messages of arbitrary length can be generated using \fBcmn_err()\fR, but if the call to \fBcmn_err()\fR 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 \fBLOG_MSGSIZE\fR bytes (see <\fBsys/log.h\fR>). For this reason, callers of \fBcmn_err()\fR that require complete and accurate message generation should post down from high-level interrupt context before calling \fBcmn_err()\fR.