September 10, 1999 FMTMSG 3

### NAME

fmtmsg - format and display a message

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```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'') .