fmtmsg(3C) DG/UX R4.11MU05 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 interface 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 components 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 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 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
identifiers may be used.
``Status subclassifications'' indicate whether the
application will recover from the condition. Identifiers
are: MMRECOVER (recoverable) and MMNRECOV (non-
recoverable).
An additional identifier, MMNULLMC, indicates that no
classification component is supplied for the message.
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 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. Produces 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 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.
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-
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
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 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
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
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'' section).
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|fmtmsg | N - - |
+---------+-----------------------------+
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 syntax",
"refer to manual", "UX:cat:001")
produces:
UX:cat: NOTE: invalid syntax
TO FIX: refer to manual UX:cat:001
SEE ALSO
reentrant(3), addseverity(3C), gettxt(3C), printf(3S).
fmtmsg(1).
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 succeeded.
MMNOCON The function was unable to generate a console message,
but otherwise succeeded.
Licensed material--property of copyright holder(s)