---
name: "fmtmsg"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/fmtmsg"
---

# fmtmsg(3)

display a detailed diagnostic message

## NAME

**fmtmsg** – display a detailed diagnostic 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 displays a detailed diagnostic message, based on the supplied arguments, to stderr and/or the system console.

The *classification* argument is the bitwise inclusive OR of zero or one of the manifest constants from each of the classification groups below. The Output classification group is an exception since both MM\_PRINT and MM\_CONSOLE may be specified.

- Output

  - MM\_PRINT

    Output should take place on stderr.

  - MM\_CONSOLE

    Output should take place on the system console.

- Source of Condition (Major)

  - MM\_HARD

    The source of the condition is hardware related.

  - MM\_SOFT

    The source of the condition is software related.

  - MM\_FIRM

    The source of the condition is firmware related.

- Source of Condition (Minor)

  - MM\_APPL

    The condition was detected at the application level.

  - MM\_UTIL

    The condition was detected at the utility level.

  - MM\_OPSYS

    The condition was detected at the operating system level.

- Status

  - MM\_RECOVER

    The application can recover from the condition.

  - MM\_NRECOV

    The application is unable to recover from the condition.

Alternatively, the MM\_NULLMC manifest constant may be used to specify no classification.

The *label* argument indicates the source of the message. It is made up of two fields separated by a colon (‘:’). The first field can be up to 10 bytes, and the second field can be up to 14 bytes. The MM\_NULLLBL manifest constant may be used to specify no label.

The *severity* argument identifies the importance of the condition. One of the following manifest constants should be used for this argument.

- MM\_HALT

  The application has confronted a serious fault and is halting.

- MM\_ERROR

  The application has detected a fault.

- MM\_WARNING

  The application has detected an unusual condition, that could be indicative of a problem.

- MM\_INFO

  The application is providing information about a non-error condition.

- MM\_NOSEV

  No severity level supplied.

The *text* argument details the error condition that caused the message. There is no limit on the size of this character string. The MM\_NULLTXT manifest constant may be used to specify no text.

The *action* argument details how the error-recovery process should begin. Upon output, **fmtmsg**() will prefix "TO FIX:" to the beginning of the *action* argument. The MM\_NULLACT manifest constant may be used to specify no action.

The *tag* argument should reference online documentation for the message. This usually includes the *label* and a unique identifying number. An example tag is "BSD:ls:168". The MM\_NULLTAG manifest constant may be used to specify no tag.

## RETURN VALUES

The **fmtmsg**() function returns MM\_OK upon success, MM\_NOMSG to indicate output to stderr failed, MM\_NOCON to indicate output to the system console failed, or MM\_NOTOK to indicate output to stderr and the system console failed.

## ENVIRONMENT

The MSGVERB (message verbosity) environment variable specifies which arguments to **fmtmsg**() will be output to stderr, and in which order. MSGVERB should be a colon (‘:’) separated list of identifiers. Valid identifiers include: label, severity, text, action, and tag. If invalid identifiers are specified or incorrectly separated, the default message verbosity and ordering will be used. The default ordering is equivalent to a MSGVERB with a value of "label:severity:text:action:tag".

## EXAMPLES

The code:

```
fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls", MM_ERROR,
    "illegal option -- z", "refer to manual", "BSD:ls:001");
```

will output:

```
BSD:ls: ERROR: illegal option -- z
TO FIX: refer to manual BSD:ls:001
```

to stderr.

The same code, with MSGVERB set to "text:severity:action:tag", produces:

```
illegal option -- z: ERROR
TO FIX: refer to manual BSD:ls:001
```

## SEE ALSO

[err(3)](/err/3.md), [exit(3)](/exit/3.md), [strerror(3)](/strerror/3.md)

## STANDARDS

The **fmtmsg**() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”).

## HISTORY

The **fmtmsg**() function first appeared in FreeBSD 5.0.

## BUGS

Specifying MM\_NULLMC for the *classification* argument makes little sense, since without an output specified, **fmtmsg**() is unable to do anything useful.

In order for **fmtmsg**() to output to the system console, the effective user must have appropriate permission to write to */dev/console*. This means that on most systems **fmtmsg**() will return MM\_NOCON unless the effective user is root.