catgetmsg(3C)                                                    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);

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


                                                                        Page 1