fmtmsg(1) USER COMMANDS fmtmsg(1)
NAME
fmtmsg - display a message on stderr or system console
SYNOPSIS
fmtmsg [-c class] [-u subclass] [-l label] [-s severity] [-t
tag] [-a action] text
DESCRIPTION
Based on a message's classification component, fmtmsg either
writes a formatted message to stderr or writes a formatted
message to the console.
A formatted message consists of up to five standard com-
ponents as defined below. The classification and subclass
components are not displayed as part of the standard mes-
sage, but rather define the source of the message and direct
the display of the formatted message. The valid options
are:
-c class Describes the source of the message. Valid key-
words are:
hard The source of the condition is
hardware.
soft The source of the condition is
software.
firm The source of the condition is
firmware.
-u subclass A list of keywords (separated by commas) that
further defines the message and directs the
display of the message. Valid keywords are:
appl The condition originated in an
application. This keyword should
not be used in combination with
either util or opsys.
util The condition originated in a
utility. This keyword should not
be used in combination with either
appl or opsys.
opsys The message originated in the ker-
nel. This keyword should not be
used in combination with either
appl or util.
recov The application will recover from
the condition. This keyword
should not be used in combination
with nrecov.
nrecov The application will not recover
from the condition. This keyword
should not be used in combination
with recov.
1
fmtmsg(1) USER COMMANDS fmtmsg(1)
print Print the message to the standard
error stream stderr.
console Write the message to the system
console. print, console, or both
may be used.
-l label Identifies the source of the message.
-s severity Indicates the seriousness of the error. The
keywords and definitions of the standard levels
of severity are:
halt The application has encountered a
severe fault and is halting.
error The application has detected a
fault.
warn The application has detected a
condition that is out of the ordi-
nary and might be a problem.
info The application is providing
information about a condition that
is not in error.
-t tag The string containing an identifier for the mes-
sage.
-a action A text string describing the first step in the
error recovery process. This string must be
written so that the entire action argument is
interpreted as a single argument. fmtmsg pre-
cedes each action string with the TO FIX: pre-
fix.
text A text string describing the condition. Must be
written so that the entire text argument is
interpreted as a single argument. The environ-
ment variables MSGVERB and SEVLEVEL control the
behavior of fmtmsg. MSGVERB is set by the
administrator in the /etc/profile for the sys-
tem. Users can override the value of MSGVERB
set by the system by resetting MSGVERB in their
own .profile files or by changing the value in
their current shell session. SEVLEVEL can be
used in shell scripts. MSGVERB tells fmtmsg
which message components to select when writing
messages to stderr. The value of MSGVERB is a
colon separated list of optional keywords.
MSGVERB can be set as follows:
MSGVERB=[keyword[:keyword[:...]]]
export MSGVERB
Valid keywords are: label, severity, text, action, and tag.
If MSGVERB contains a keyword for a component and the
component's value is not the component's null value, fmtmsg
2
fmtmsg(1) USER COMMANDS fmtmsg(1)
includes that component in the message when writing the mes-
sage to stderr. If MSGVERB 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 MSGVERB 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,
fmtmsg selects all components. MSGVERB affects only which
message components are selected for display. All message
components are included in console messages.
SEVLEVEL defines severity levels and associates print
strings with them for use by fmtmsg. The standard severity
levels shown below cannot be modified. Additional severity
levels can be defined, redefined, and removed.
0 (no severity is used)
1 HALT
2 ERROR
3 WARNING
4 INFO
SEVLEVEL is set as follows:
SEVLEVEL=[description[:description[:...]]]
export SEVLEVEL
description is a comma-separated list containing three
fields:
description=severity_keyword,level,printstring
severity_keyword is a character string used as the keyword
with the -s severity option to fmtmsg. level is a character
string that evaluates to a positive integer (other than 0,
1, 2, 3, or 4, which are reserved for the standard severity
levels). If the keyword severity_keyword is used, level is
the severity value passed on to fmtmsg(3C). printstring is
the character string used by fmtmsg in the standard message
format whenever the severity value level is used.
If SEVLEVEL is not defined, or if its value is null, no
severity levels other than the defaults are available. If a
description 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 posi-
tive integer, that description in the colon separated list
is ignored.
DIAGNOSTICS
The exit codes for fmtmsg are the following:
0 All the requested functions were executed success-
fully.
1 The command contains a syntax error, an invalid
3
fmtmsg(1) USER COMMANDS fmtmsg(1)
option, or an invalid argument to an option.
2 The function executed with partial success, how-
ever the message was not displayed on stderr.
4 The function executed with partial success, how-
ever the message was not displayed on the system
console.
32 No requested functions were executed successfully.
EXAMPLES
Example 1: The following example of fmtmsg produces a com-
plete message in the standard message format and displays it
to the standard error stream:
fmtmsg -c soft -u recov,print,appl -l UX:cat -s error
-t UX:cat:001 -a "refer to manual" "invalid syntax"
produces:
UX:cat: ERROR: invalid syntax
TO FIX: refer to manual UX:cat:138
Example 2: When the environment variable MSGVERB is set as
follows:
MSGVERB=severity:text:action
and Example 1 is used, fmtmsg produces:
ERROR: invalid syntax
TO FIX: refer to manual
Example 3: When the environment variable SEVLEVEL is set
as follows:
SEVLEVEL=note,5,NOTE
the following fmtmsg command:
fmtmsg -c soft -u print -l UX:cat -s note -a "refer to
manual" "invalid syntax"
produces:
UX:cat: NOTE: invalid syntax
TO FIX: refer to manual
and displays the message on stderr.
SEE ALSO
addsverity(3C), fmtmsg(3C) in the Programmer's Reference
Manual.
4