fmtmsg(3C)

DESCRIPTION

The fmtmsg() routine is intended as a language-independent error message service. 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 control.

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 MM_NULLMC. If this is done, no message is produced. The class types are:

The remaining parameters are functionally optional, in that the message produced may exclude any or all of them. Each is discussed in parameter 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 specifying the subsystem in error. For example,

This component can be excluded by setting it to MM_NULLLBL or NULL.

The severity component describes the degree of importance of the failure. The predefined severity levels are:

The text component describes the nature of the failure in the most specific 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 MM_NULLTXT or MM_NULL.

The action component describes the options available for recovery from the error. As output, it is prefaced with the string TO FIX:. It may be disabled by setting action to MM_NULLACT or NULL.

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 MM_NULLTXT or RMM_NULL.

EXTERNAL INFLUENCES

The user may control the appearance of the message produced on standard error through the use of two environment variables: MSGVERB and SEV_LEVEL. These have no effect on the console message.

The MSGVERB environment variable describes the components the user is interested in seeing. The value of MSGVERB 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 MSGVERB are displayed when fmtmsg() is called; all other components 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 MSGVERB format. If MSGVERB is erroneous or unset, fmtmsg() produces the full message.

The SEV_LEVEL environment variable gives users control over the text string displayed for the severity component if the severity is other than those described above. The predefined severity levels (MM_NOSEV through MM_HALT) cannot be overridden.

The value of SEV_LEVEL is a list of one or more level specifiers separated by colons. A level specifier is a three item comma list of the form identifier, level, message. The identifier is not used by fmtmsg(), and is only included for compatibility. It is not optional, however, as fmtmsg() 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 severity field, in the same manner as HALT and INFO are displayed for the MM_HALT and MM_INFO severities. Level specifiers having more or fewer than three items are invalid, as are null level specifiers. Invalid or null valued SEV_LEVEL lists have no impact on the behavior of fmtmsg().

RETURN VALUE

The fmtmsg() routine returns one of the following values on exit:

AUTHOR

fmtmsg() was developed by OSF and HP.

SEE ALSO

printf(3S), thread_safety(5).

STANDARDS COMPLIANCE

fmtmsg: SVID3