catmsgfmt(3C)                                                    catmsgfmt(3C)


NAME
     catmsgfmt - 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 ALSO
     caterr(1), explain(1), gencat(1), whichcat(1), catgetmsg(3C),
     catgets(3C), catopen(3C), strftime(3C), nl_types(5).


                                                                        Page 1