353 lines
8.5 KiB
Groff
353 lines
8.5 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g1.fmtmsg @(#)fmtmsg 41.1 of 5/28/91
|
|
.\" Copyright 1989 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} fmtmsg 1 "Essential Utilities" "\&"
|
|
.if \nX=1 .ds x} fmtmsg 1 "Essential Utilities"
|
|
.if \nX=2 .ds x} fmtmsg 1 "" "\&"
|
|
.if \nX=2 .ds x} fmtmsg "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4fmtmsg\f1 \- display a message on \f4stderr\f1 or system console
|
|
.SH SYNOPSIS
|
|
.na
|
|
\f4fmtmsg\f1
|
|
[\f4\-c\f2 class\f1]
|
|
[\f4\-u\f2 subclass\f1]
|
|
[\f4\-l\f2 label\f1]
|
|
[\f4\-s\f2 severity\f1]
|
|
[\f4\-t\f2 tag\f1]
|
|
[\f4\-a\f2 action\f1] \f2 text
|
|
.ad
|
|
.SH DESCRIPTION
|
|
Based on a message's classification component,
|
|
\f4fmtmsg\f1 either writes a formatted message
|
|
to \f4stderr\f1 or
|
|
writes a formatted message to the console.
|
|
.PP
|
|
A formatted message consists of up to five standard
|
|
components as defined below.
|
|
The classification and subclass components are not displayed
|
|
as part of the standard message, but rather define the source of the
|
|
message and direct the display of the formatted message.
|
|
The valid options are:
|
|
.TP 12
|
|
\f4\-c \f2class\f1\f1
|
|
Describes the source of the message.
|
|
Valid keywords are:
|
|
.PP
|
|
.RS 16
|
|
.PD 0
|
|
.TP 10
|
|
\f4hard\f1
|
|
The source of the condition is hardware.
|
|
.TP
|
|
\f4soft\f1
|
|
The source of the condition is software.
|
|
.TP
|
|
\f4firm\f1
|
|
The source of the condition is firmware.
|
|
.PD
|
|
.RE
|
|
.TP 12
|
|
\f4\-u \f2subclass\f1\f1
|
|
A list of keywords (separated by commas)
|
|
that further defines the message and directs the display of the message.
|
|
Valid keywords are:
|
|
.P
|
|
.RS 16
|
|
.PD 0
|
|
.TP 10
|
|
\f4appl\f1
|
|
The condition originated in an application.
|
|
This keyword should not be used in combination with either
|
|
\f4util\f1 or \f4opsys\f1.
|
|
.TP
|
|
\f4util\f1
|
|
The condition originated in a utility.
|
|
This keyword should not be used in combination with either
|
|
\f4appl\f1 or \f4opsys\f1.
|
|
.TP
|
|
\f4opsys\f1
|
|
The message originated in the kernel.
|
|
This keyword should not be used in combination with either
|
|
\f4appl\f1 or \f4util\f1.
|
|
.TP
|
|
\f4recov\f1
|
|
The application will recover from the
|
|
condition.
|
|
This keyword should not be used in combination with
|
|
\f4nrecov\f1.
|
|
.TP
|
|
\f4nrecov\f1
|
|
The application will not recover from the condition.
|
|
This keyword should not be used in combination with
|
|
\f4recov\f1.
|
|
.TP
|
|
\f4print\f1
|
|
Print the message to the standard error stream \f4stderr\f1.
|
|
.TP
|
|
\f4console\f1
|
|
Write the message to the system console.
|
|
\f4print\f1, \f4console\fP, or both may be used.
|
|
.RE
|
|
.PD
|
|
.TP 12
|
|
\f4\-l \f2label\f1\f1
|
|
Identifies the source of the message.
|
|
.TP
|
|
\f4\-s \f2severity\f1\f1
|
|
Indicates the seriousness of the error.
|
|
The keywords and definitions of the
|
|
standard levels of \f2severity\f1 are:
|
|
.P
|
|
.RS 16
|
|
.PD 0
|
|
.TP 10
|
|
\f4halt\f1
|
|
The application has encountered a severe fault and is halting.
|
|
.TP
|
|
\f4error\f1
|
|
The application has detected a fault.
|
|
.TP
|
|
\f4warn\f1
|
|
The application has detected a condition that is out of the ordinary and
|
|
might be a problem.
|
|
.TP
|
|
\f4info\f1
|
|
The application is providing information about a condition that is not in
|
|
error.
|
|
.RE
|
|
.PD
|
|
.TP 12
|
|
\f4\-t \f2tag\f1\f1
|
|
The string containing an identifier for the message.
|
|
.TP
|
|
\f4\-a \f2action\f1\f1
|
|
A text string describing the first step in the error recovery process.
|
|
This string must be written so that the entire \f2action\f1
|
|
argument is interpreted as a single argument.
|
|
\f4fmtmsg\f1 precedes each action string with the
|
|
\f4TO FIX:\f1 prefix.
|
|
.TP
|
|
\f2text\f1
|
|
A text string describing the condition.
|
|
Must be written so that the entire \f2text\f1
|
|
argument is interpreted as a single argument.
|
|
.P
|
|
The environment variables \f4MSGVERB\f1 and
|
|
\f4SEV_LEVEL\f1 control the behavior of \f4fmtmsg\f1.
|
|
\f4MSGVERB\f1 is set by the administrator in the
|
|
\f4/etc/profile\f1 for the system.
|
|
Users can override the value of \f4MSGVERB\f1 set by the system
|
|
by resetting \f4MSGVERB\f1
|
|
in their own \f4.profile\f1 files or by changing the value
|
|
in their current shell session.
|
|
\f4SEV_LEVEL\f1 can be used in shell scripts.
|
|
.P
|
|
\f4MSGVERB\f1 tells \f4fmtmsg\f1 which message
|
|
components to select when writing messages
|
|
to \f4stderr\f1.
|
|
The value of \f4MSGVERB\f1 is a
|
|
colon separated list of optional keywords.
|
|
\f4MSGVERB\f1 can be
|
|
set as follows:
|
|
.P
|
|
.RS 6
|
|
.nf
|
|
\f4MSGVERB=\f1[\f2keyword\f1[\f4:\f2keyword\f1[\f4:\f1. . .]]]
|
|
\f4export MSGVERB\f1
|
|
.fi
|
|
.RE
|
|
.P
|
|
Valid \f2keywords\f1 are:
|
|
\f4label\f1,
|
|
\f4severity\f1, \f4text\f1, \f4action\f1, and \f4tag\f1.
|
|
If \f4MSGVERB\f1
|
|
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\f1 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\f1 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.
|
|
.P
|
|
\f4MSGVERB\f1 affects only which message components are selected
|
|
for display.
|
|
All message components are included in console messages.
|
|
.PP
|
|
\f4SEV_LEVEL\f1 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 be defined, redefined, and removed.
|
|
.P
|
|
.RS
|
|
.PD 0
|
|
.TP 4
|
|
\f40\f1
|
|
(no severity is used)
|
|
.TP
|
|
\f41
|
|
HALT
|
|
.TP
|
|
2
|
|
ERROR
|
|
.TP
|
|
3
|
|
WARNING
|
|
.TP
|
|
4
|
|
INFO\f1
|
|
.RE
|
|
.PD
|
|
.br
|
|
.ne 1.5i
|
|
.PP
|
|
\f4SEV_LEVEL\f1 is set as follows:
|
|
.PP
|
|
.RS
|
|
\f4SEV_LEVEL=\f1[\f2description\f1[\f4:\f2description\f1[\f4:\f1...]]]
|
|
.br
|
|
\f4export SEV_LEVEL\f1
|
|
.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 used as the keyword
|
|
with the \f4\-s\f1 \f2severity\f1 option to \f4fmtmsg\f1.
|
|
.P
|
|
.I level
|
|
is a character string that evaluates to a positive integer
|
|
(other than \f40\f1, \f41\f1, \f42\f1, \f43\f1, or \f44\f1,
|
|
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 \f4fmtmsg\f1(3C).
|
|
.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 \f4SEV_LEVEL\f1 is not defined, or if its value is null,
|
|
no severity levels other than the defaults are available.
|
|
If a \f2description\f1 in
|
|
the colon separated list is not a comma separated list
|
|
containing three fields,
|
|
or if the second field of a comma separated list
|
|
does not evaluate to a positive integer,
|
|
that \f2description\f1 in the colon separated list is ignored.
|
|
.PP
|
|
.SH DIAGNOSTICS
|
|
The exit codes for \f4fmtmsg\f1 are the following:
|
|
.RS
|
|
.TP
|
|
\f40\f1
|
|
All the requested functions were executed successfully.
|
|
.TP
|
|
\f41\f1
|
|
The command contains a syntax error, an invalid option,
|
|
or an invalid argument to an option.
|
|
.TP
|
|
\f42\f1
|
|
The function executed with partial success, however
|
|
the message was not displayed on \f4stderr\f1.
|
|
.TP
|
|
\f44\f1
|
|
The function executed with partial success, however the message
|
|
was not displayed on the system console.
|
|
.TP
|
|
\f432\f1
|
|
No requested functions were executed successfully.
|
|
.RE
|
|
.SH EXAMPLES
|
|
Example 1:
|
|
The following example of \f4fmtmsg\f1
|
|
produces a complete message in the standard message format
|
|
and displays it to the standard error stream:
|
|
.PP
|
|
.RS
|
|
\f4fmtmsg
|
|
\-c soft
|
|
\-u recov,print,appl
|
|
\-l UX:cat
|
|
\-s error -t UX:cat:001
|
|
\-a "refer to manual" "invalid syntax"\fP
|
|
.RE
|
|
.PP
|
|
produces:
|
|
.P
|
|
.RS
|
|
.nf
|
|
\f5UX:cat: ERROR: invalid syntax
|
|
TO FIX: refer to manual UX:cat:138\fP
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Example 2:
|
|
When the environment variable \f4MSGVERB\f1 is set as follows:
|
|
.PP
|
|
.RS
|
|
\f4MSGVERB=severity:text:action\fP
|
|
.RE
|
|
.br
|
|
.ne 1.5i
|
|
.PP
|
|
and Example 1 is used, \f4fmtmsg\f1 produces:
|
|
.P
|
|
.RS
|
|
\f5ERROR: invalid syntax
|
|
.br
|
|
TO FIX: refer to manual\fP
|
|
.RE
|
|
.PP
|
|
Example 3:
|
|
When the environment variable \f4SEV_LEVEL\f1 is set as follows:
|
|
.PP
|
|
.RS
|
|
\f4SEV_LEVEL=note,5,NOTE\fP
|
|
.RE
|
|
.PP
|
|
the following \f4fmtmsg\f1 command:
|
|
.PP
|
|
.RS
|
|
\f4fmtmsg
|
|
\-c soft
|
|
\-u print
|
|
\-l UX:cat
|
|
\-s note
|
|
\-a "refer to manual" "invalid syntax"\fP
|
|
.RE
|
|
.PP
|
|
produces:
|
|
.P
|
|
.RS
|
|
\f5UX:cat: NOTE: invalid syntax
|
|
.br
|
|
TO FIX: refer to manual\fP
|
|
.RE
|
|
.PP
|
|
and displays the message on \f4stderr\f1.
|
|
.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
|
|
\f4addseverity\fP(3C), \f4fmtmsg\fP(3C)
|