catgets() — Read a program message

Standards

Standards / Extensions C or C++ Dependencies

XPG4
XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE
#include <nl_types.h>

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

General description

The catgets() function attempts to read message msg_id, in set set_id, from the message catalog identified by catd. The catd argument is a message catalog descriptor returned from an earlier call to catopen(). The s argument points to a default message string which will be returned by catgets() if it cannot retrieve the identified message.

When message source files are processed by the gencat command, the CODESET used to create them is saved in the resulting message catalog. The catgets() function interrogates this CODESET value to see if it differs from the CODESET value of the current locale. If it does differ then catgets() uses the iconv() function to convert the message text coming from the message catalog into the codeset of the current locale. The default message string (s) is not affected by this conversion. If iconv() does not support the conversion specified by the two CODESETs then the default message string is returned.

Returned value

If the identified message is retrieved successfully, catgets() returns a pointer to an internal buffer area containing the NULL-terminated message string.

If unsuccessful, catgets() returns s and sets errno to one of the following values:
Error Code
Description
EBADF
The catd argument is not a valid message catalog descriptor open for reading.
EINTR
The read operation was terminated due to the receipt of a signal, and no data was transferred.
Special behavior for z/OS® UNIX Services:
Error Code
Description
EINVAL
May be returned for several reasons:
  • The message catalog identified by catd is not a valid message catalog, or has been corrupted. Ensure that the message catalog was created using the z/OS UNIX gencat command.
  • iconv() does not support the conversion between the codeset of the message catalog and that of the current locale. To check the codeset that the message catalog was created in, look for the codeset name at offset 28 into the message catalog.
ENOMSG
The message identified by set_id and msg_id is not in the message catalog.

Related information

Parent topic: Library functions