catgets(S)

catgets -- read a program message

Syntax

cc . . . -lc

#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 msg_id, in set set_id, 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:

I_EBADC: The set_id and msg_id values are out of range.
I_EBADF: Invalid message catalog descriptor.
I_ENMEM: Could not allocate memory allocation while executing.
I_ENMSG: No message in the file for this combination of set_id and msg_id values; however, the values are not out of range.
I_EREAD: 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 identified 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.

Standards conformance

catgets is conformant with: