catmsgfmt(3C)

NAME
     catmsgfmt - Formats an error message

SYNOPSIS
     UNICOS systems:

     #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]]);

     IRIX systems:

     #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);

IMPLEMENTATION
     UNICOS systems

     IRIX systems

STANDARDS
     CRI extension

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
     catgetmsg(3C), catgets(3C), catopen(3C) describe message system
     library functions
     strftime(3C) describes time-stamp formatting

     caterr(1), explain(1), gencat(1), whichcat(1) describe message system
     user commands in the UNICOS User Commands Reference Manual,
     publication SR-2011

     nl_types(5) describes the file that defines message system variables
     for use in programs in the UNICOS File Formats and Special Files
     Reference Manual, publication SR-2014

     Cray Message System Programmer's Guide, publication SG-2121, contains
     details about all aspects of the message system

     UNICOS System Libraries Reference Manual, publication SR-2080, for the
     printed version of this man page.