catgets(S)                     6 January 1993                     catgets(S)


 Name

    catgets - read a program message

 Syntax


    cc  . . .  -lintl


    #include  <nl_types.h>

    char *catgets (catd, set_id, msg_id, defmsg)
    nl_catd catd;
    int set_id, msg_id;
    char *defmsg;


 Description

    catgets attempts to read message msgid, in set setid, from the message
    catalog identified by catd.  catd is a catalog descriptor returned from
    an earlier call to catopen(S).  The defmsg argument points to a default
    message string which is returned by catgets if it cannot retrieve the
    identified message.

    catgets fails if any of the following is true:

    IEBADC     The setid and msgid values are out of range.

    IEBADF     Invalid message catalog descriptor.

    IENMEM     Could not allocate memory allocation while executing.

    IENMSG     No message in the file for this combination of setid and
                msgid values; however, the values are not out of range.

    IEREAD     The message could not be read.


 Return value

    If the identified message is retrieved successfully, catgets returns a
    pointer to an internal buffer area containing the null terminated message
    string.  If the call is unsuccessful because the message catalog identi-
    fied by catd is not currently available, or if the message catalog is
    available, but the identified message is not contained therein, ``s'' (a
    pointer to the default message) is returned.

 Application usage

    The message-text is contained in an internal buffer area and should be
    copied by the application if it is to be saved or reused after further
    calls to catgets.

 See also

    catopen(S)

 Standards conformance

    catgets is conformant with:
    X/Open Portability Guide, Issue 3, 1989.