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
The fmtmsg() function writes a formatted message to stderr,
to the console, or to both, on a message's classification
component. It can be used instead of the traditional
printf(3C) interface to display messages to stderr, and in
conjunction with gettxt(3C), provides a simple interface for
producing language-independent applications.
A formatted message consists of up to five standard com-
ponents ( label, severity, text, action, and tag) as
described below. The classification component 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).
o "Major classifications" identify the source of
the condition. Identifiers are: MM_HARD
(hardware), MM_SOFT (software), and MM_FIRM
(firmware).
o "Message source subclassifications" identify the
type of software in which the problem is spot-
ted. Identifiers are: MM_APPL (application),
MM_UTIL (utility), and MM_OPSYS (operating sys-
tem).
o "Display subclassifications" indicate where the
message is to be displayed. Identifiers are:
MM_PRINT to display the message on the standard
error stream, MM_CONSOLE to display the message
on the system console. Neither, either, or both
identifiers may be used.
o "Status subclassifications" indicate whether the
application will recover from the condition.
Identifiers are: MM_RECOVER (recoverable) and
MM_NRECOV (non-recoverable).
o An additional identifier, MM_NULLMC, 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 Sys-
tem V package and the cat(1) utility.
severity
Indicates the seriousness of the condition. Identif-
iers for the standard levels of severity are:
o MM_HALT indicates that the application has
encountered a severe fault and is halting. Pro-
duces the print string HALT.
o MM_ERROR indicates that the application has
detected a fault. Produces the print string
ERROR.
o MM_WARNING indicates a condition out of the
ordinary that might be a problem and should be
watched. Produces the print string WARNING.
o MM_INFO provides information about a condition
that is not in error. Produces the print string
INFO.
o MM_NOSEV 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: TOFIX:. The action string is not lim-
ited 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
The MSGVERB and SEV_LEVEL environment variables control the
behavior of fmtmsg() as follows:
MSGVERB
This variable determines which message components
fmtmsg() selects when writing messages to stderr. Its
value is a colon-separated list of optional keywords
and 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 mes-
sage. 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 con-
tains keywords other than the valid ones listed above,
fmtmsg() selects all components.
The first time fmtmsg() is called, it examines MSGVERB
to determine which message components are to be
selected when generating a message to write to the
standard error stream, stderr. The values accepted on
the initial call are saved for future calls.
The MSGVERB environment variable affects only those
components that are selected for display to the stan-
dard error stream. All message components are included
in console messages.
SEV_LEVEL
This variable defines severity levels and associates
print strings with them for use by fmtmsg(). The stan-
dard severity levels listed below cannot be modified.
Additional severity levels can also be defined, rede-
fined, and removed using addseverity() (see
addseverity(3C)). If the same severity level is
defined by both SEV_LEVEL and addseverity(), the
definition by addseverity() takes precedence.
0 (no severity is used)
1 HALT
2 ERROR
3 WARNING
4 INFO
The SEV_LEVEL variable can be set as follows:
SEV_LEVEL=[description[:description[:...]]]
export SEV_LEVEL
where description is a comma-separated list containing three
fields:
description=severity_keyword,level,printstring
The severity_keyword field is a character string that is
used as the keyword on the -s severity option to the
fmtmsg(1) utility. (This field is not used by the fmtmsg()
function.)
The level field 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() function.
The printstring field is the character string used by
fmtmsg() in the standard message format whenever the sever-
ity 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
SEV_LEVEL environment variable, if defined, to deter-
mine 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 MM_NULLLBL |
| severity int 0 MM_NULLSEV |
| class long 0L MM_NULLMC |
| text char* (char*) NULL MM_NULLTXT |
| action char* (char*) NULL MM_NULLACT |
| tag char* (char*) NULL MM_NULLTAG |
|_________________________________________________________________|
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
above).
RETURN VALUES
The fmtmsg() returns the following values:
MM_OK The function succeeded.
MM_NOTOK
The function failed completely.
MM_NOMSG
The function was unable to generate a message on the
standard error stream, but otherwise succeeded.
MM_NOCON
The function was unable to generate a console message,
but otherwise succeeded.
EXAMPLES
Example 1: The following example of fmtmsg():
fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "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 SEV_LEVEL is set as
follows:
SEV_LEVEL=note,5,NOTE
the following call to fmtmsg()
fmtmsg(MM_UTIL | MM_PRINT, "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
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
fmtmsg(1), addseverity(3C), gettxt(3C), printf(3C), attri-
butes(5)
Man(1) output converted with
man2html