'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1994, Sun Microsystems, Inc.  All Rights Reserved
.\" 2003, Sun Microsystems, Inc.  All Rights Reserved
.\" 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 fmtmsg 1 "20 Jul 1994" "SunOS 5.11" "User Commands"
.SH NAME
fmtmsg \- display a message on stderr or system console
.SH SYNOPSIS
.LP
.nf
\fBfmtmsg\fR [\fB-c\fR \fIclass\fR] [\fB-u\fR \fIsubclass\fR] [\fB-l\fR \fIlabel\fR] [\fB-s\fR \fIseverity\fR] 
     [\fB-t\fR \fItag\fR] [\fB-a\fR \fIaction\fR] \fItext\fR
.fi

.SH DESCRIPTION
.sp
.LP
Based on a message's classification component, the \fBfmtmsg\fR utility either
writes a formatted message to \fBstderr\fR or writes a formatted message to the
console.
.sp
.LP
A formatted message consists of up to five standard components (see environment
variable \fBMSGVERB\fR in the ENVIRONMENT VARIABLES section of this page). The
classification and subclass components are not displayed as part of the
standard message, but rather define the source of the message and direct the
display of the formatted message.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-c\fR \fIclass\fR \fR
.ad
.RS 16n
.rt  
Describes the source of the message. Valid keywords are:
.sp
.ne 2
.mk
.na
\fB\fBhard\fR \fR
.ad
.RS 9n
.rt  
The source of the condition is hardware.
.RE

.sp
.ne 2
.mk
.na
\fB\fBsoft\fR \fR
.ad
.RS 9n
.rt  
The source of the condition is software.
.RE

.sp
.ne 2
.mk
.na
\fB\fBfirm\fR \fR
.ad
.RS 9n
.rt  
The source of the condition is firmware.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-u\fR \fIsubclass\fR \fR
.ad
.RS 16n
.rt  
A list of keywords (separated by commas) that further defines the message and
directs the display of the message. Valid keywords are:
.sp
.ne 2
.mk
.na
\fB\fBappl\fR \fR
.ad
.RS 12n
.rt  
The condition originated in an application. This keyword should not be used in
combination with either \fButil\fR or \fBopsys\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fButil\fR \fR
.ad
.RS 12n
.rt  
The condition originated in a utility. This keyword should not be used in
combination with either \fBappl\fR or \fBopsys\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBopsys\fR \fR
.ad
.RS 12n
.rt  
The message originated in the kernel. This keyword should not be used in
combination with either \fBappl\fR or \fButil\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBrecov\fR \fR
.ad
.RS 12n
.rt  
The application will recover from the condition. This keyword should not be
used in combination with \fBnrecov\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBnrecov\fR \fR
.ad
.RS 12n
.rt  
The application will not recover from the condition. This keyword should not be
used in combination with \fBrecov\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBprint\fR \fR
.ad
.RS 12n
.rt  
Print the message to the standard error stream \fBstderr\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBconsole\fR \fR
.ad
.RS 12n
.rt  
Write the message to the system console. \fBprint\fR, \fBconsole\fR, or both
may be used.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-l\fR \fIlabel\fR \fR
.ad
.RS 16n
.rt  
Identifies the source of the message.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR \fIseverity\fR \fR
.ad
.RS 16n
.rt  
Indicates the seriousness of the error. The keywords and definitions of the
standard levels of \fIseverity\fR are:
.sp
.ne 2
.mk
.na
\fB\fBhalt\fR \fR
.ad
.RS 9n
.rt  
The application has encountered a severe fault and is halting.
.RE

.sp
.ne 2
.mk
.na
\fB\fBerror\fR\fR
.ad
.RS 9n
.rt  
The application has detected a fault.
.RE

.sp
.ne 2
.mk
.na
\fB\fBwarn\fR\fR
.ad
.RS 9n
.rt  
The application has detected a condition that is out of the ordinary and might
be a problem.
.RE

.sp
.ne 2
.mk
.na
\fB\fBinfo\fR \fR
.ad
.RS 9n
.rt  
The application is providing information about a condition that is not in
error.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR \fItag\fR \fR
.ad
.RS 16n
.rt  
The string containing an identifier for the message.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-a\fR \fIaction\fR \fR
.ad
.RS 16n
.rt  
A text string describing the first step in the error recovery process. This
string must be written so that the entire \fIaction\fR argument is interpreted
as a single argument. \fBfmtmsg\fR precedes each action string with the \fBTO
FIX:\fR prefix.
.RE

.sp
.ne 2
.mk
.na
\fB\fItext\fR \fR
.ad
.RS 16n
.rt  
A text string describing the condition. Must be written so that the entire
\fItext\fR argument is interpreted as a single argument.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRStandard message format
.sp
.LP
The following example of \fBfmtmsg\fR produces a complete message in the
standard message format and displays it to the standard error stream.

.sp
.in +2
.nf
example% \fBfmtmsg -c soft -u recov,print,appl -l UX:cat \e
     -s error -t UX:cat:001 -a "refer to manual" "invalid syntax"\fR
.fi
.in -2
.sp

.sp
.LP
produces:

.sp
.in +2
.nf
UX:cat: ERROR: invalid syntax 
TO FIX: refer to manual   UX:cat:138
.fi
.in -2
.sp

.LP
\fBExample 2 \fRUsing MSGVERB
.sp
.LP
When the environment variable \fBMSGVERB\fR is set as follows:

.sp
.in +2
.nf
\fBMSGVERB=severity:text:action\fR
.fi
.in -2
.sp

.sp
.LP
and Example 1 is used, \fBfmtmsg\fR produces:

.sp
.in +2
.nf
ERROR: invalid syntax 
TO FIX: refer to manual
.fi
.in -2
.sp

.LP
\fBExample 3 \fRUsing SEV_LEVEL
.sp
.LP
When the environment variable \fBSEV_LEVEL\fR is set as follows:

.sp
.in +2
.nf
\fBSEV_LEVEL=note,5,NOTE\fR
.fi
.in -2
.sp

.sp
.LP
the following \fBfmtmsg\fR command:

.sp
.in +2
.nf
example% \fBfmtmsg -c soft -u print -l UX:cat -s note \e
     -a "refer to manual" "invalid syntax"\fR
.fi
.in -2
.sp

.sp
.LP
produces:

.sp
.in +2
.nf
NOTE: invalid syntax
TO FIX: refer to manual
.fi
.in -2
.sp

.sp
.LP
and displays the message on \fBstderr\fR.

.SH ENVIRONMENT VARIABLES
.sp
.LP
The environment variables \fBMSGVERB\fR and \fBSEV_LEVEL\fR control the
behavior of \fBfmtmsg\fR. \fBMSGVERB\fR is set by the administrator in the
\fB/etc/profile\fR for the system. Users can override the value of
\fBMSGVERB\fR set by the system by resetting \fBMSGVERB\fR in their own
\fB\&.profile\fR files or by changing the value in their current shell session.
\fBSEV_LEVEL\fR can be used in shell scripts.
.sp
.LP
\fBMSGVERB\fR tells \fBfmtmsg\fR which message components to select when
writing messages to \fBstderr\fR. The value of \fBMSGVERB\fR is a
colon-separated list of optional keywords. \fBMSGVERB\fR can be set as follows:
.sp
.in +2
.nf
\fBMSGVERB=[\fIkeyword\fR[:\fIkeyword\fR[:...]]]
export MSGVERB\fR
.fi
.in -2
.sp

.sp
.LP
Valid \fIkeyword\fRs are: \fBlabel\fR, \fBseverity\fR, \fBtext\fR,
\fBaction\fR, and \fBtag\fR. If \fBMSGVERB\fR contains a keyword for a
component and the component's value is not the component's null value,
\fBfmtmsg\fR includes that component in the message when writing the message to
\fBstderr\fR. If \fBMSGVERB\fR does not include a keyword for a message
component, that component is not included in the display of the message. The
keywords may appear in any order. If \fBMSGVERB\fR is not defined, if its value
is the null string, if its value is not of the correct format, or if it
contains keywords other than the valid ones listed above, \fBfmtmsg\fR selects
all components.
.sp
.LP
\fBMSGVERB\fR affects only which message components are selected for display.
All message components are included in console messages.
.sp
.LP
\fBSEV_LEVEL\fR defines severity levels and associates print strings with them
for use by \fBfmtmsg\fR. The standard severity levels shown below cannot be
modified. Additional severity levels can be defined, redefined, and removed.
.sp
.ne 2
.mk
.na
\fB\fB0\fR \fR
.ad
.RS 6n
.rt  
(no severity is used)
.RE

.sp
.ne 2
.mk
.na
\fB\fB1\fR \fR
.ad
.RS 6n
.rt  
\fBHALT\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fB2\fR \fR
.ad
.RS 6n
.rt  
\fBERROR\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fB3\fR \fR
.ad
.RS 6n
.rt  
\fBWARNING\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fB4\fR \fR
.ad
.RS 6n
.rt  
\fBINFO\fR
.RE

.sp
.LP
\fBSEV_LEVEL\fR is set as follows:
.sp
.LP
\fIdescription\fR is a comma-separated list containing three fields:
.sp
.in +2
.nf
\fBSEV_LEVEL=   [\fIdescription\fR[:\fIdescription\fR[:...]]]
export SEV_LEVEL\fR
.fi
.in -2
.sp

.sp
.LP
\fIdescription\fR=\fIseverity_keyword\fR, \fIlevel\fR, \fIprintstring\fR
.sp
.LP
\fIseverity_keyword\fR is a character string used as the keyword with the
\fB-s\fR \fIseverity\fR option to \fBfmtmsg\fR.
.sp
.LP
\fIlevel\fR is a character string that evaluates to a positive integer (other
than \fB0\fR, \fB1\fR, \fB2\fR, \fB3\fR, or \fB4\fR, which are reserved for the
standard severity levels). If the keyword \fIseverity_keyword\fR is used,
\fIlevel\fR is the severity value passed on to \fBfmtmsg\fR(3C).
.sp
.LP
\fIprintstring\fR is the character string used by \fBfmtmsg\fR in the standard
message format whenever the severity value \fIlevel\fR is used.
.sp
.LP
If \fBSEV_LEVEL\fR is not defined, or if its value is null, no severity levels
other than the defaults are available. If a \fIdescription\fR in the colon
separated list is not a comma separated list containing three fields, or if the
second field of a comma separated list does not evaluate to a positive integer,
that \fIdescription\fR in the colon separated list is ignored.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR \fR
.ad
.RS 7n
.rt  
All the requested functions were executed successfully.
.RE

.sp
.ne 2
.mk
.na
\fB\fB1\fR \fR
.ad
.RS 7n
.rt  
The command contains a syntax error, an invalid option, or an invalid argument
to an option.
.RE

.sp
.ne 2
.mk
.na
\fB\fB2\fR \fR
.ad
.RS 7n
.rt  
The function executed with partial success, however the message was not
displayed on \fBstderr\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB4\fR \fR
.ad
.RS 7n
.rt  
The function executed with partial success; however, the message was not
displayed on the system console.
.RE

.sp
.ne 2
.mk
.na
\fB\fB32\fR \fR
.ad
.RS 7n
.rt  
No requested functions were executed successfully.
.RE

.SH SEE ALSO
.sp
.LP
\fBaddseverity\fR(3C), \fBfmtmsg\fR(3C), \fBattributes\fR(5)