fmtmsg(3C) LIBRARY FUNCTIONS 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 formatted message to stderr, to the console, or to both.
fmtmsg can be used instead of the traditional printf inter-
face to display messages to stderr. fmtmsg, in conjunction
with gettxt, provides a simple interface for producing
language-independent applications.
A formatted message consists of up to five standard com-
ponents as defined below. The component, classification, is
not part of the standard 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
classifications and subclassifications. Any one iden-
tifier 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 spotted.
Identifiers are: MMAPPL (application), MMUTIL
(utility), and MMOPSYS (operating system).
``Display subclassifications'' indicate where the
message is to be displayed. Identifiers are:
MMPRINT to display the message on the standard
error stream, MMCONSOLE to display the message on
the system console. Neither, either, or both iden-
tifiers may be used.
1
fmtmsg(3C) LIBRARY FUNCTIONS fmtmsg(3C)
``Status subclassifications'' indicate whether the
application will recover from the condition. Iden-
tifiers are: MMRECOVER (recoverable) and MMNRECOV
(non-recoverable).
An additional identifier, MMNULLMC, indicates that
no classification component is supplied for the mes-
sage.
label
Identifies the source of the message. The format of
this component 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 exam-
ple, the label UX:cat indicates the UNIX System V pack-
age 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 encoun-
tered 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 sup-
plied for the message.
Additional severity levels may be added by using the
addseverity routine.
text
Describes the condition that produced 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 prefix: TO FIX:. The action string is not
limited to a specific size.
2
fmtmsg(3C) LIBRARY FUNCTIONS fmtmsg(3C)
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.
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-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 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.
The first time fmtmsg is called, it examines the MSGVERB
environment variable to see which message components it is
to select when generating 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 com-
ponents 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:
3
fmtmsg(3C) LIBRARY FUNCTIONS fmtmsg(3C)
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 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 severity_keyword is used,
level is the severity value passed on to the fmtmsg func-
tion. 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 positive integer, that description in the
colon list is ignored.
The first time fmtmsg is called, it examines the SEVLEVEL
environment 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 messages generated by an application by using the null
value of the argument 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 variable (see the ``Environment Variables'' sec-
tion).
4
fmtmsg(3C) LIBRARY FUNCTIONS fmtmsg(3C)
DIAGNOSTICS
The exit codes for fmtmsg are the following:
MMOK The function succeeded.
MMNOTOK The function failed completely.
MMNOMSG The function was unable to generate a message on
the standard error stream, but otherwise suc-
ceeded.
MMNOCON The function was unable to generate a console
message, but otherwise succeeded.
EXAMPLES
Example 1:
The following example of fmtmsg:
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 syn-
tax", "refer to manual", "UX:cat:001")
produces:
UX:cat: NOTE: invalid syntax
TO FIX: refer to manual UX:cat:001
SEE ALSO
addseverity(3C), gettxt(3C), printf(3S).
5
fmtmsg(3C) LIBRARY FUNCTIONS fmtmsg(3C)
fmtmsg(1) in the User's Reference Manual.
6