Tribblix: manual page: fmtmsg.3c

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