396 lines
11 KiB
Plaintext
396 lines
11 KiB
Plaintext
'\"! tbl | mmdoc
|
|
'\"macro stdmacro
|
|
.if n .pH g3s.fmtmsg @(#)fmtmsg @(#)fmtmsg 41.3
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} fmtmsg 3C "Essential Utilities" "\&"
|
|
.if \nX=1 .ds x} fmtmsg 3C "Essential Utilities"
|
|
.if \nX=2 .ds x} fmtmsg 3C "" "\&"
|
|
.if \nX=3 .ds x} fmtmsg "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4fmtmsg\f1 \- display a message on \f4stderr\f1 or system console
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f4#include <fmtmsg.h>
|
|
.PP
|
|
\f4int fmtmsg(long classification, const char *label, int severity,
|
|
.br
|
|
.nf
|
|
const char *text, const char *action, const char *tag)\fP;
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Based on a message's classification component,
|
|
\f4fmtmsg\f1 writes a formatted message
|
|
to \f4stderr\f1, to the console,
|
|
or to both.
|
|
.PP
|
|
\f4fmtmsg\f1 can be used instead of the traditional \f4printf\f1 interface
|
|
to display messages to \f4stderr\fP.
|
|
\f4fmtmsg\f1, in conjunction with \f4gettxt\f1, provides a
|
|
simple interface for producing language-independent
|
|
applications.
|
|
.PP
|
|
A formatted message consists of up to five standard
|
|
components as defined below.
|
|
The component, \f2classification\f1, 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.
|
|
.TP 6
|
|
.I 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 \f4stderr\f1
|
|
and the system console).
|
|
.IP "" 9
|
|
``Major classifications''
|
|
identify the source of the condition.
|
|
Identifiers are:
|
|
\f4MM_HARD\f1 (hardware), \f4MM_SOFT\f1 (software),
|
|
and \f4MM_FIRM\f1 (firmware).
|
|
.IP
|
|
``Message source subclassifications''
|
|
identify the type of software in which the problem is spotted.
|
|
Identifiers are: \f4MM_APPL\f1 (application), \f4MM_UTIL\f1 (utility),
|
|
and \f4MM_OPSYS\f1 (operating system).
|
|
.IP
|
|
``Display subclassifications''
|
|
indicate where the message is to be displayed.
|
|
Identifiers are: \f4MM_PRINT\f1 to display the message
|
|
on the standard error stream, \f4MM_CONSOLE\f1 to
|
|
display the message on the system console.
|
|
Neither, either, or both identifiers may be used.
|
|
.IP
|
|
``Status subclassifications''
|
|
indicate whether the application will recover from the
|
|
condition.
|
|
Identifiers are: \f4MM_RECOVER\f1 (recoverable)
|
|
and \f4MM_NRECOV\f1 (non-recoverable).
|
|
.IP
|
|
An additional identifier, \f4MM_NULLMC\f1, indicates
|
|
that no classification component
|
|
is supplied for the message.
|
|
.TP 6
|
|
.I 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 \f2label\f1 identifies the
|
|
package in which the application resides
|
|
as well as the program or application name.
|
|
For example, the \f2label\f1 \f4UX:cat\f1
|
|
indicates the
|
|
.SM UNIX
|
|
System V package and the
|
|
\f4cat\fP application.
|
|
.TP 6
|
|
.I severity
|
|
Indicates the seriousness of the condition.
|
|
Identifiers for the
|
|
standard levels of \f2severity\f1 are:
|
|
.IP "" 9
|
|
\f4MM_HALT\f1
|
|
indicates that the application has
|
|
encountered a severe fault and is halting.
|
|
Produces the print string \f5HALT\fP.
|
|
.IP
|
|
\f4MM_ERROR\f1
|
|
indicates that the application has detected a fault.
|
|
Produces the print string \f5ERROR\fP.
|
|
.IP
|
|
\f4MM_WARNING\f1
|
|
indicates a condition out of the ordinary
|
|
that might be a problem and should be watched.
|
|
Produces the print string \f5WARNING\fP.
|
|
.IP
|
|
\f4MM_INFO\f1
|
|
provides information about a condition that is not in error.
|
|
Produces the print string \f5INFO\fP.
|
|
.IP
|
|
\f4MM_NOSEV\f1
|
|
indicates that no severity level is supplied for the message.
|
|
.PP
|
|
.RS 6
|
|
Other severity levels may be added
|
|
by using the \f4addseverity\f1 routine.
|
|
.RE
|
|
.TP 6
|
|
.I text
|
|
Describes the condition that produced the message.
|
|
The \f2text\f1 string is not limited to a specific size.
|
|
.TP 6
|
|
.I action
|
|
Describes the first step to be taken in the
|
|
error recovery process.
|
|
\f4fmtmsg\f1 precedes each action string with the prefix:
|
|
\f5TO FIX:\fP.
|
|
The \f2action\f1 string is not limited to a specific size.
|
|
.TP 6
|
|
.I tag
|
|
An identifier which references on-line documentation
|
|
for the message.
|
|
Suggested usage is that \f2tag\f1
|
|
includes the \f2label\f1 and a unique identifying number.
|
|
A sample \f2tag\f1 is \f4UX:cat:146\fP.
|
|
.SS Environment Variables
|
|
There are two environment variables that control the
|
|
behavior of \f4fmtmsg\f1:
|
|
\f4MSGVERB\fP and \f4SEV_LEVEL\fP.
|
|
.P
|
|
\f4MSGVERB\fP tells \f4fmtmsg\f1 which message
|
|
components it is to select when writing messages
|
|
to \f4stderr\f1.
|
|
The value of \f4MSGVERB\fP is a
|
|
colon-separated list of optional keywords.
|
|
\f4MSGVERB\fP can be
|
|
set as follows:
|
|
.P
|
|
.RS
|
|
.nf
|
|
\f4MSGVERB=\f1[\f2keyword\f1[\f4:\f2keyword\f1[\f4:\f1...]]]
|
|
\f4export MSGVERB\f1
|
|
.fi
|
|
.RE
|
|
.P
|
|
Valid \f2keywords\f1 are:
|
|
\f4label\fP,
|
|
\f4severity\fP,
|
|
\f4text\fP,
|
|
\f4action\fP,
|
|
and
|
|
\f4tag\fP.
|
|
If \f4MSGVERB\fP
|
|
contains a keyword for a component and the
|
|
component's value is not the component's null value,
|
|
\f4fmtmsg\f1 includes that component in the message when
|
|
writing the message to \f4stderr\f1.
|
|
If \f4MSGVERB\fP 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 \f4MSGVERB\fP 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, \f4fmtmsg\f1 selects all components.
|
|
.PP
|
|
The first time \f4fmtmsg\f1 is called, it
|
|
examines the \f4MSGVERB\fP environment variable to see
|
|
which message components it is to select when generating a
|
|
message to write to the standard error stream,
|
|
\f4stderr\f1.
|
|
The values accepted on the initial call
|
|
are saved for future calls.
|
|
.PP
|
|
\f4MSGVERB\fP affects only which components are selected
|
|
for display to the standard error stream.
|
|
All message components are included in console messages.
|
|
.PP
|
|
\f4SEV_LEVEL\fP defines severity levels and associates
|
|
print strings with them for use by \f4fmtmsg\f1.
|
|
The standard severity levels shown below cannot be modified.
|
|
Additional severity levels can also be defined, redefined, and removed
|
|
using \f4addseverity\f1 [see \f4addseverity\f1(3C)].
|
|
If the same severity level is defined by both
|
|
\f4SEV_LEVEL\f1 and \f4addseverity\f1,
|
|
the definition by \f4addseverity\f1 is controlling.
|
|
.PP
|
|
.RS
|
|
.PD 0
|
|
.TP 4
|
|
0
|
|
(no severity is used)
|
|
.TP
|
|
1
|
|
\f5HALT\fP
|
|
.TP
|
|
2
|
|
\f5ERROR\fP
|
|
.TP
|
|
3
|
|
\f5WARNING\fP
|
|
.TP
|
|
4
|
|
\f5INFO\fP
|
|
.RE
|
|
.PD
|
|
.PP
|
|
\f4SEV_LEVEL\fP can be set as follows:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\f4SEV_LEVEL=\f1[\f2description\f1[\f4:\f2description\f1[\f4:\f1...]]]
|
|
\f4export SEV_LEVEL\f1
|
|
.fi
|
|
.RE
|
|
.P
|
|
\f2description\f1 is a comma-separated list
|
|
containing three fields:
|
|
.P
|
|
.RS
|
|
\f2description\f4=\f2severity_keyword\f4,\f2level\f4,\f2printstring\f1
|
|
.RE
|
|
.P
|
|
.I severity_keyword
|
|
is a character string that is used as the keyword
|
|
on the \f4\-s \f2severity\f1 option to the \f4fmtmsg\fP
|
|
command.
|
|
(This field is not used by the \f4fmtmsg\f1
|
|
function.)
|
|
.P
|
|
.I 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 \f2severity_keyword\f1 is used,
|
|
\f2level\f1 is the severity value passed on to the \f4fmtmsg\f1
|
|
function.
|
|
.P
|
|
.I printstring
|
|
is the character string used by \f4fmtmsg\f1 in the
|
|
standard message format whenever the severity value
|
|
\f2level\f1 is used.
|
|
.PP
|
|
If a \f2description\f1 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 \f2description\f1 in the colon list is ignored.
|
|
.PP
|
|
The first time \f4fmtmsg\f1 is called, it
|
|
examines the \f4SEV_LEVEL\fP
|
|
environment variable, if defined, to see whether the
|
|
environment expands the levels of severity beyond the
|
|
five standard levels and those defined using \f4addseverity\f1.
|
|
The values accepted on the initial call
|
|
are saved for future calls.
|
|
.SS 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.
|
|
.PP
|
|
The table below indicates the null values and identifiers
|
|
for \f4fmtmsg\f1 arguments.
|
|
.sp
|
|
.TS
|
|
box, center, tab(;);
|
|
c c c c
|
|
lI lf4 lf4 lf4.
|
|
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
|
|
.TE
|
|
.PP
|
|
Another means of systematically omitting
|
|
a component is by omitting
|
|
the component keyword(s) when defining
|
|
the \f4MSGVERB\fP environment variable
|
|
(see the ``Environment Variables'' section).
|
|
.SH EXAMPLES
|
|
Example 1:
|
|
.PP
|
|
The following example of \f4fmtmsg\f1:
|
|
.PP
|
|
.RS
|
|
\f4fmtmsg(MM_PRINT, "UX:cat", MM_ERROR,
|
|
"invalid syntax",
|
|
"refer to manual", "UX:cat:001")\fP
|
|
.RE
|
|
.PP
|
|
produces a complete message in the standard message format:
|
|
.PP
|
|
.RS
|
|
\f4UX:cat: ERROR: invalid syntax
|
|
.br
|
|
TO FIX: refer to manual UX:cat:001\fP
|
|
.RE
|
|
.PP
|
|
Example 2:
|
|
.PP
|
|
When the environment variable \f4MSGVERB\fP is set as
|
|
follows:
|
|
.PP
|
|
.RS
|
|
\f4MSGVERB=severity:text:action\fP
|
|
.RE
|
|
.PP
|
|
and the Example 1 is used, \f4fmtmsg\f1 produces:
|
|
.PP
|
|
.RS
|
|
\f4ERROR: invalid syntax
|
|
.br
|
|
TO FIX: refer to manual\fP
|
|
.RE
|
|
.br
|
|
.PP
|
|
Example 3:
|
|
.PP
|
|
When the environment variable \f4SEV_LEVEL\fP is set as
|
|
follows:
|
|
.PP
|
|
.RS
|
|
\f4SEV_LEVEL=note,5,NOTE\fP
|
|
.RE
|
|
.PP
|
|
the following call to \f4fmtmsg\f1:
|
|
.PP
|
|
.RS
|
|
\f4fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5,
|
|
"invalid syntax",
|
|
"refer to manual", "UX:cat:001")\fP
|
|
.RE
|
|
.sp .5
|
|
produces:
|
|
.PP
|
|
.RS
|
|
\f4UX:cat: NOTE: invalid syntax
|
|
.br
|
|
TO FIX: refer to manual UX:cat:001\fP
|
|
.RE
|
|
.SH NOTES
|
|
A slightly different standard error message format
|
|
and a new developer interface, \f(CWpfmt\fP,
|
|
is being introduced as the replacement
|
|
for \f(CWfmtmsg\fP.
|
|
A similar interface, \f(CWlfmt\fP, is also being
|
|
introduced for producing a standard format message
|
|
and forwarding messages to the console and/or
|
|
to the system message logging and monitoring facilities.
|
|
\f(CWfmtmsg\fP will be removed at a future time.
|
|
.SH SEE ALSO
|
|
\f4fmtmsg\fP(1),
|
|
\f4addseverity\fP(3C), \f4gettxt\fP(3C), \f4printf\fP(3S).
|
|
.SH DIAGNOSTICS
|
|
The exit codes for \f4fmtmsg\fP are the following:
|
|
.TP 12
|
|
\f4MM_OK\fP
|
|
The function succeeded.
|
|
.TP
|
|
\f4MM_NOTOK\fP
|
|
The function failed completely.
|
|
.TP
|
|
\f4MM_NOMSG\fP
|
|
The function was unable to generate a message on the standard
|
|
error stream, but otherwise succeeded.
|
|
.TP
|
|
\f4MM_NOCON\fP
|
|
The function was unable to generate a console message, but otherwise succeeded.
|