catgets() — Retrieve a Message from a Message Catalog
Format
#include <nl_types.h>
char *catgets(nl_catd catd, int set_id, int msg_id, char *s);
Language Level
XPG4
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE category of the current locale. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Integrated File System Interface
This function is not available when SYSIFCOPT(*NOIFSIO) is specified on the compilation command.
Description
The catgets()
function
retrieves message msg_id, in set set_id from
the message catalog that is identified by catd. catd is
a message catalog descriptor that is returned by a previous call to catopen()
. The s argument
points to a default message which will be returned by catgets()
if
the identified message cannot be retrieved.
Return Value
If the message is retrieved
successfully, then
catgets()
returns
a pointer to the message string that is contained in the message catalog.
The CCSID of the retrieved message is determined by the flags specified
in the oflag parameter on the previous call to the catopen()
function,
when the message catalog file was opened. - If the NL_CAT_JOB_MODE flag was specified, then the retrieved message is in the CCSID of the job.
- If the NL_CAT_CTYPE_MODE flag was specified, then the retrieved message is in the CCSID of the LC_CTYPE category of the current locale.
- If neither flag was specified, the CCSID of the retrieved message matches the CCSID of the message catalog file.
The value of
errno
can be set to the
following: - EBADF
- The catalog descriptor is not valid.
- ECONVERT
- A conversion error occurred.
- EINTR
- The function was interrupted by a signal.
Example
#include <stdio.h>
#include <nl_types.h>
#include <locale.h>
/* Name of the message catalog is "/qsys.lib/mylib.lib/msgs.usrspc" */
int main(void) {
nl_catd msg_file;
char * my_msg;
char * my_locale;
setlocale(LC_ALL, NULL);
msg_file = catopen("/qsys.lib/mylib.lib/msgs.usrspc", 0);
if (msg_file != CATD_ERR) {
my_msg = catgets(msg_file, 1, 2, "oops");
printf("%s\n", my_msg);
catclose(msg_file);
}
}