catgetmsg(3C)

NAME
     catgetmsg - Reads a message from a message catalog

SYNOPSIS
     #include <nl_types.h>

     char *catgetmsg (nl_catd catd, int set_num, int msg_num, char (*buf,
     int buflen);

IMPLEMENTATION
     UNICOS systems

     IRIX systems

STANDARDS
     CRI extension

DESCRIPTION
     The catgetmsg function returns the requested message string.  The
     message string is placed in the user-supplied buffer (pointed to by
     buf) and terminated with a null byte.  If the message is longer than
     buflen bytes, it is truncated with a null byte.

     The catd argument is a catalog descriptor returned from an earlier
     call to catopen(3C); it identifies the message catalog that contains
     the message identified by the message set (set_num) and the message
     number (msg_num).

     The set_num and msg_num arguments are defined as integer values for
     maximum portability.  However, it is recommended that programmers use
     symbolic names for message and set numbers wherever possible, rather
     than having integer values hard-coded into their source programs.  The
     NL_MSGSET macro in the nl_types.h file must be passed as the set_num
     argument.

NOTES
     You can use the catgetmsg and catgets(3C) functions to retrieve
     messages from a message catalog.  On UNICOS systems, catgetmsg is
     optimized for programs that retrieve only a few messages, while
     catgets(3C) is optimized for programs that retrieve many messages.  On
     IRIX systems, catgetmsg and catgets have comparable performance.

     Specifically, catgetmsg minimizes memory usage at the expense of more
     frequent disk accesses.  The catgets(3C) function minimizes disk
     accesses at the expense of more memory usage.  If it is important to
     your application to minimize usage of one of these resources, use the
     corresponding function.

RETURN VALUES
     If successful, catgetmsg returns a pointer to the message string in
     buf.

     If catgetmsg is unsuccessful because the message catalog identified by
     catd is not currently available, or the requested message is not in
     the message catalog, a pointer to a null ("") string is returned.

SEE ALSO
     catgets(3C), catmsgfmt(3C), catopen(3C) describe message system
     library functions

     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.