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 message is retrieved unsuccessfully, then a pointer to the default string s is returned.

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 that uses catgets()

#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);
   }
}

Related Information


[ Top of Page | Previous Page | Next Page | Contents | Index ]