FMTMSG(3) | Library Functions Manual | FMTMSG(3) |
fmtmsg
— display a
detailed diagnostic message
Standard C Library (libc, -lc)
#include
<fmtmsg.h>
int
fmtmsg
(long classification,
const char *label, int severity,
const char *text, const char
*action, const char *tag);
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.
MM_PRINT
stderr
.MM_CONSOLE
MM_RECOVER
MM_NRECOV
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
MM_ERROR
MM_WARNING
MM_INFO
MM_NOSEV
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.
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.
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
".
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
The fmtmsg
() function conforms to
IEEE Std 1003.1-2001 (“POSIX.1”).
The fmtmsg
() function first appeared in
FreeBSD 5.0.
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.
August 5, 2002 | macOS 14.6 |