|
|
|
#include <fmtmsg.h>
int fmtmsg(long classification,
const char *label,
int severity,
const char *text,
const char *action,
const char *tag);
Safe
fmtmsg() can be used instead of the traditional printf.3s 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.
Other severity levels may be added by using the addseverity() routine.
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.
SEV_LEVEL 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 SEV_LEVEL and addseverity() , the definition by addseverity() is controlling.
SEV_LEVEL can be set as follows:
SEV_LEVEL=[description[:description[:...]]] export SEV_LEVEL
description is a comma-separated list containing three fields:
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() 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
SEV_LEVEL
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.
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).
The following example of fmtmsg():
produces a complete message in the standard message format:
Example 2:
When the environment variable MSGVERB is set as follows:
and the Example 1 is used, fmtmsg() produces:
Example 3:
When the environment variable SEV_LEVEL is set as follows:
the following call to fmtmsg() :
|
|
|
Created by unroff & hp-tools. © by Hans-Peter Bischof. All Rights Reserved (1997).
Last modified 21/April/97