fmtmsg(3C) fmtmsg(3C)
NAME
fmtmsg - display a message on stderr or system console
SYNOPSIS
#include <fmtmsg.h>
int fmtmsg(long classification, const char *label, int severity,
const char *text, const char *action, const char *tag);
DESCRIPTION
Based on a message's classification component, fmtmsg() writes a for-
matted message to stderr, to the console, or to both.
fmtmsg() can be used instead of the usual printf() interface to
display messages to stderr. fmtmsg(), in conjunction with gettxt(),
provides a simple interface for producing language-independent appli-
cations.
A formatted message consists of up to five standard components as
defined below. The component, classification, is not part of the stan-
dard message displayed to the user, but rather defines the source of
the message and directs the display of the formatted message.
classification
Contains identifiers from the following groups of major clas-
sifications and subclassifications. Any one identifier from a
subclass may be used in combination by ORing the values
together with a single identifier from a different subclass.
Two or more identifiers from the same subclass should not be
used together, with the exception of identifiers from the
display subclass. Both display subclass identifiers may be
used so that messages can be displayed to both stderr and the
system console.
"Major classifications"
Identify the source of the condition. Identifiers are:
MMHARD (hardware), MMSOFT (software), and MMFIRM
(firmware).
"Message source subclassifications"
Identify the type of software in which the problem is
detected. Identifiers are: MMAPPL (application),
MMUTIL (utility), and MMOPSYS (operating system).
"Display subclassifications"
Indicate where the message is to be displayed. Identif-
iers are: MMPRINT to display the message on the stan-
dard error stream, MMCONSOLE to display the message on
the system console. Neither, either, or both identifiers
may be used.
Page 1 Reliant UNIX 5.44 Printed 11/98
fmtmsg(3C) fmtmsg(3C)
"Status subclassifications"
Indicate whether the application will recover from the
condition. Identifiers are: MMRECOVER (recoverable) and
MMNRECOV (nonrecoverable).
An additional identifier, MMNULLMC, indicates that no clas-
sification component is supplied for the message.
label Identifies the source of the message. The format of this com-
ponent is two fields separated by a colon. The first field is
up to 10 characters long; the second is up to 14 characters.
Suggested usage is that label identifies the package in which
the application resides as well as the program or application
name. For example, the label UX:cat indicates the UNIX System
V package and the cat application.
severity Indicates the seriousness of the condition. Identifiers for
the standard levels of severity are:
MMHALT Indicates that the application has encountered
a severe fault and is halting. Produces the
print string "HALT".
MMERROR Indicates that the application has detected a
fault. Produces the print string "ERROR".
MMWARNING Indicates a condition out of the ordinary that
might be a problem and should be watched. Pro-
duces the print string "WARNING".
MMINFO Provides information about a condition that is
not in error. Produces the print string
"INFO".
MMNOSEV Indicates that no severity level is supplied
for the message.
Other severity levels may be added by using the addseverity()
routine.
text Describes the reason for the message. The text string is not
limited to a specific size.
action Describes the first step to be taken in the error recovery
process. fmtmsg() precedes each action string with the pre-
fix: "TO FIX:". The action string is not limited to a
specific size.
tag An identifier which references on-line documentation for the
message. Suggested usage is that tag includes the label and a
unique identifying number. A sample tag is "UX:cat:146".
Page 2 Reliant UNIX 5.44 Printed 11/98
fmtmsg(3C) fmtmsg(3C)
Environment variables
There are two environment variables that control the behavior of
fmtmsg(): MSGVERB and SEVLEVEL.
MSGVERB tells fmtmsg() which message components it is 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() includes that component in the
message when writing the message 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 com-
ponents.
The first time fmtmsg() is called, it examines the MSGVERB environment
variable to see which message components it is to select when generat-
ing a message to write to the standard error stream, stderr. The
values accepted on the initial call are saved for future calls.
MSGVERB affects only which components are selected for display to the
standard error stream. 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 also be defined,
redefined, and removed using addseverity [see addseverity(3C)]. If the
same severity level is defined by both SEVLEVEL and addseverity(),
the definition by addseverity() is controlling.
0 (no severity is used)
1 HALT
2 ERROR
3 WARNING
4 INFO
SEVLEVEL can be set as follows:
SEVLEVEL=[description[:description[:...]]]
export SEVLEVEL
Page 3 Reliant UNIX 5.44 Printed 11/98
fmtmsg(3C) fmtmsg(3C)
description is a comma-separated list containing three fields:
description=severitykeyword,level,printstring
severitykeyword is a character string that is used as the keyword on
the -s severity option to the fmtmsg() command. This field is not used
by the fmtmsg() function.
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 severitykeyword is used, level is
the severity value passed on to the fmtmsg() function.
printstring is the character string used by fmtmsg() in the standard
message format whenever the severity value level is used.
If a description in the colon list is not a three-field comma list,
or, if the second field of a comma list does not evaluate to a posi-
tive integer, that description in the colon list is ignored.
The first time fmtmsg() is called, it examines the SEVLEVEL environ-
ment variable, if defined, to see whether the environment expands the
levels of severity beyond the five standard levels and those defined
using addseverity(). The values accepted on the initial call are saved
for future calls.
Use in Applications
One or more message components may be systematically omitted from mes-
sages generated by an application by using the null value of the argu-
ment for that component.
The table below indicates the null values and identifiers for fmtmsg()
arguments.
Argument Type Null-value Identifier
____________________________________________
label char* (char*) NULL MMNULLLBL
severity int 0 MMNULLSEV
class long 0L MMNULLMC
text char* (char*) NULL MMNULLTXT
action char* (char*) NULL MMNULLACT
tag char* (char*) NULL MMNULLTAG
Another means of systematically omitting a component is by omitting
the component keyword(s) when defining the MSGVERB environment vari-
able (see the "Environment variables" section).
Page 4 Reliant UNIX 5.44 Printed 11/98
fmtmsg(3C) fmtmsg(3C)
EXAMPLES
Example 1:
fmtmsg(MMPRINT, "UX:cat", MMERROR, "invalid syntax", \
"refer to manual", "UX:cat:001")
produces a complete message in the standard message format:
UX:cat: ERROR: invalid syntax
TO FIX: refer to manual UX:cat:001
Example 2: When the environment variable MSGVERB is set as follows:
MSGVERB=severity:text:action
and the 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 call to fmtmsg():
fmtmsg(MMUTIL | MMPRINT, "UX:cat", 5, "invalid syntax", \
"refer to manual", "UX:cat:001")
produces the following output:
UX:cat: NOTE: invalid syntax
TO FIX: refer to manual UX:cat:001
RESULT
The exit codes for fmtmsg() are the following:
MMOK The function succeeded.
MMNOTOK The function was not successfully executed.
MMNOMSG The function was unable to generate a message on the stan-
dard error stream, but otherwise succeeded.
MMNOCON The function was unable to generate a console message, but
otherwise succeeded.
SEE ALSO
fmtmsg(1), addseverity(3C), gettxt(3C), printf(3S).
Page 5 Reliant UNIX 5.44 Printed 11/98