catmsgfmt(3C)catmsgfmt(3C)NAMEcatmsgfmt - formats an error message
SYNOPSIS
fixed: .nf #include <nl_types.h>
char *catmsgfmt (const char *cmdname, const char *groupcode, int msgnum,
const char *severity, const char *msgtext, char *buf, int buflen,
const char *position, const char *debug);
DESCRIPTION
The catmsgfmt function produces a formatted message that consists of the
command name (cmdname), group code (groupcode), message number (msgnum),
severity level (severity), message text (msgtext), and optional position
(position) and debugging (debug) information. The formatted message is
placed in the user-supplied buffer, which is pointed to by buf, and
terminated with a null byte. If the formatted message is longer than
buflen bytes, it is truncated to buflen bytes with a null byte.
The cmdname, groupcode, severity, msgtext, and optional position and
debug arguments are null-terminated strings. The command name identifies
the command or function issuing the error message. Typically, the group
code is the same value as that specified as the name parameter on the
catopen(3C) function. Typically, the message number is the same value as
that specified on the catgetmsg(3C) or catgets(3C) function.
The position and debug arguments are optional. Their contents are
inserted in the error message only if provided and only if included in
the MSG_FORMAT environment variable. Specifying a null value for either
(or both) parameters is equivalent to not specifying either (or both)
parameters.
NOTES
The MSG_FORMAT environment variable controls the formatting of the
message. If the MSG_FORMAT environment variable is not defined, a
default format is used. See the explain(1) man page for a description of
message formats and the MSG_FORMAT environment variable.
MSG_FORMAT can include an optional time stamp for the message. The
format of this time stamp is equivalent to that produced by the
cftime(3C) function and can be overridden by the CFTIME environment
variable. For a description of time-stamp formats, see the strftime(3C)
man page.
RETURN VALUES
If successful, catmsgfmt returns a pointer to the user-supplied buffer.
If unsuccessful, it returns a null pointer.
SEE ALSOcaterr(1), explain(1), gencat(1), whichcat(1), catgetmsg(3C),
catgets(3C), catopen(3C), strftime(3C), nl_types(5).
Page 1
