FMTMSG(3C) Standard C 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
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 components (
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
spotted. Identifiers are:
MM_APPL (application),
MM_UTIL (utility), and
MM_OPSYS (operating system).
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 System V
package and the
cat(1) utility.
severity Indicates the seriousness of the condition. Identifiers
for the standard levels of
severity are:
o
MM_HALT indicates that the application has
encountered a severe fault and is halting.
Produces 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
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
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 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
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 standard
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 standard severity
levels listed 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
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
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
SEV_LEVEL environment variable, if defined, to determine 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(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
fmtmsg(1),
addseverity(3C),
gettxt(3C),
printf(3C),
attributes(7),
standards(7) July 24, 2002
FMTMSG(3C)