catgets -- Read a Message

Format

#include <nl_types.h>
char *catgets(nl_catd catd, int set_id, int msg_id, char *s);

Language Level: XPG4
catgets retrieves message msg_id, in set set_id from the message catalog identified by catd. catd is a message catalog descriptor returned by a previous call to catopen. s points to a default message that catgets returns if the identified message cannot be retrieved.

The message string catgets retrieves is a format-string that you can use with printf or sprintf. This string may contain placeholders for message inserts; therefore, you need to supply values when the message string is formatted. See example.

If catgets finds the specified message, it loads it into an internal character string buffer, ends the message string with a null character, and returns a pointer to the buffer.

The returned pointer is used to reference the buffer and display the message. However, once you close the catalog, the buffer cannot be referenced.

Return Value
If the get is successful, then catgets returns the retrieved message. If the get is unsuccessful, then catgets returns the user-supplied default message string specified by the s parameter.

To indicate the error, the value of errno is set to:

EBADF The catd argument is not a valid message catalog descriptor open for reading.
ENOMSG The message identified by set_id and msg_id is not in the message catalog.

Example



catclose -- Close Message Catalog
catopen -- Open Message Catalog
<nl_types.h>