FMTMSG(3)

FMTMSG(3) | Library Functions Manual | FMTMSG(3)

# NAME

`fmtmsg` —
format and display a message

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <fmtmsg.h>`

int
`fmtmsg`(long classification, const char *label, int severity, const char *text, const char *action, const char *tag);

# DESCRIPTION

The `fmtmsg`() function can be used to display messages in the specified format. Messages may be written either to standard error, to the console, or both.

A formatted message consists of up to five components specified in label, severity, text, action and tag. Further information such as the origin of the message, the recoverability from the condition causing the message and where to display the message is specified in classification.

## Classification

The classification argument consists of a major classification and several sub-classifications. It has no effect on the content of the message displayed. With the exception of the display sub-classification, only a single identifier may be specified for each (sub-)classification. The following classifications are available:

Major classifications
  The source of the condition. Available identifiers are: `MM_HARD` (hardware), `MM_SOFT` (software), and `MM_FIRM` (firmware).
Message source sub-classifications
  The type of software detecting the condition. Available identifiers are: `MM_APPL` (application), `MM_UTIL` (utility), and `MM_OPSYS` (operating system).
Display sub-classifications
  The displays the formatted messages is to be written to. Available identifiers are: `MM_PRINT` (standard error stream) and `MM_CONSOLE` (system console).
Status sub-classifications
  The capability of the calling software to recover from the condition. Available identifiers are: `MM_RECOVER` (recoverable) and `MM_NRECOV` (non-recoverable).

If no classification is to be supplied, `MM_NULLMC` must be specified.

## Label

The label argument identifies the source of the message. It consists of two fields separated by a colon (:). The first field is up to 10 characters, the second is up to 14 characters.

If no label is to be supplied, `MM_NULLLBL` must be specified.

## Severity

The seriousness of the condition causing the message. The following severity levels are available:

`MM_HALT`
  The software has encountered a severe fault and is halting.
`MM_ERROR`
  The software has encountered a fault.
`MM_WARNING`
  The software has encountered an unusual non-fault condition.
`MM_INFO`
  The software informs about a non-error condition.

If no severity level is to be supplied, `MM_NOSEV` must be specified.

## Text

The description of the condition the software encountered. The character string is not limited to a specific size.

If no text is to be supplied, `MM_NOTXT` must be specified.

## Action

The first step to be taken to recover from the condition the software encountered; it will be preceded by the prefix “TO FIX:”. The character string is not limited to a specific size.

If no action is to be supplied, `MM_NOACT` must be specified.

## Tag

The on-line documentation which provides further information about the condition and the message, such as “fmtmsg(3)”. The character string is not limited to a specific size.

If no tag is to be supplied, `MM_NOTAG` must be specified.

Further effect on the formatting of the message as displayed on the standard error stream (but not on the system console!) may be taken by setting the `MSGVERB` environment variable, which selects the subset of message components to be printed. It consists of a colon-separated list of the optional keywords label, severity, text, action, and tag, which correspond to the arguments to `fmtmsg`() with the same names. If `MSGVERB` is either not set or malformed (containing empty or unknown keywords), its content is ignored an all message components will be selected.

Note that displaying a message on the system console may fail due to inappropriate privileges or a non-permissive file mode of the console device.

# RETURN VALUES

The `fmtmsg`() function returns one of the following values:

`MM_OK`
  The function succeeded.
`MM_NOTOK`
  The function failed completely.
`MM_NOMSG`
  The function was unable to generate a message on standard error, but otherwise succeeded.
`MM_NOCOM`
  The function was unable to generate a message on the console, but otherwise succeeded.

# SEE ALSO

printf(3), syslog(3)

# STANDARDS

The `fmtmsg`() function conforms to X/Open System Interfaces and Headers Issue 5 (“XSH5”).

April 11, 2011 | NetBSD 9.3