fmtmsg(3C)fmtmsg(3C)NAMEfmtmsg() - displays formatted message on standard error and console
SYNOPSISDESCRIPTION
The routine is intended as a language-independent error message ser‐
vice. Messages are displayed on the system console, standard error, or
both, depending on the setting of the class parameter. The format of
messages is under the control of the user, who may specify how much of
the message is to be displayed on standard error. However, the format
of the message displayed to the system console is not under user con‐
trol.
All messages specify a class, which indicates the source and status of
the error condition, and where the message should be directed. The
class may be functionally excluded by specifying If this is done, no
message is produced. The class types are:
The display class has allowable values of
which directs the message to standard error,
which directs the message to the system con‐
sole, or which directs the message to both.
The error type class may be one of
indicating a hardware error, indicating a
software failure, or which indicates a
firmware error.
The error source class may be one of
indicating an application, indicating an OS
utility, or indicating a system error.
The recovery status class may be one of
indicating recovery from the error is possi‐
ble, or stating no recovery is possible.
The remaining parameters are functionally optional, in that the message
produced may exclude any or all of them. Each is discussed in parame‐
ter order.
The label component states where the error originated. It has the form
major:minor, where major is a 10 character field specifying the major
system producing the message and minor is a 14 character field specify‐
ing the subsystem in error. For example,
This component can be excluded by setting it to or
The severity component describes the degree of importance of the fail‐
ure. The predefined severity levels are:
No severity is specified and no print string is generated.
The message is informational only and the
string is generated.
The situation might be in error, and should be checked.
The string is generated.
An error has been detected.
The string is generated.
An unrecoverable error has been detected.
The string is generated.
The text component describes the nature of the failure in the most spe‐
cific terms. It is expected to provide a sufficiently detailed account
of the error to remove all doubt about its cause. It may be excluded
by setting text to or
The action component describes the options available for recovery from
the error. As output, it is prefaced with the string It may be dis‐
abled by setting to or
The tag component is intended to direct the user to the appropriate
documentation to correct or avoid the error. It may be disabled by
setting tag to or
EXTERNAL INFLUENCES
The user may control the appearance of the message produced on standard
error through the use of two environment variables: and These have no
effect on the console message.
The environment variable describes the components the user is inter‐
ested in seeing. The value of is a list of one or more components,
separated by colons if more than one is specified. All components with
non-NULL values listed in are displayed when is called; all other com‐
ponents are excluded. Only the component names label, severity, text,
action, and tag are valid list elements. Any others (or an empty list)
are considered an error in format. If is erroneous or unset, produces
the full message.
The environment variable gives users control over the text string dis‐
played for the severity component if the severity is other than those
described above. The predefined severity levels through cannot be
overridden.
The value of is a list of one or more level specifiers separated by
colons. A level specifier is a three item comma list of the form iden‐
tifier, level, message. The identifier is not used by and is only
included for compatibility. It is not optional, however, as expects it
when examining level specifiers for the other two parts. The level is
a number greater than four indicating the level defined. The message
is a string to be displayed in the field, in the same manner as and are
displayed for the and severities. Level specifiers having more or
fewer than three items are invalid, as are null level specifiers.
Invalid or null valued lists have no impact on the behavior of
RETURN VALUE
The routine returns one of the following values on exit:
Success.
Failure.
Failure to standard error, success to the system console.
Success to standard error, failure to the system console.
AUTHOR
was developed by OSF and HP.
SEE ALSOprintf(3S), thread_safety(5).
STANDARDS COMPLIANCEfmtmsg(3C)
