catopen() — Open Message Catalog
Format
#include <nl_types.h>
nl_catd catopen(const char *name, int oflag);
Language Level
XPG4
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_MESSAGES 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 catopen()
function
opens a message catalog, which must be done before a message can be
retrieved. The NLSPATH environment variable and the LC_MESSAGES category
are used to find the specified message catalog if no slash (/) characters
are found in the name. If the name contains one or more slash (/)
characters, then the name is interpreted as a path name of the catalog
to open.
If there is no NLSPATH environment variable, or if a message catalog cannot be found in the path specified by NLSPATH, then a default path is used. The default path might be affected by the setting of the LANG environment variable; if the NL_CAT_LOCALE flag is set in the oflag parameter or if the LANG environment variable is not set, the default path might be affected by the LC_MESSAGES locale category.
Three values can be specified for the oflag parameter: NL_CAT_LOCALE, NL_CAT_JOB_MODE, and NL_CAT_CTYPE_MODE. NL_CAT_JOB_MODE and NL_CAT_CTYPE_MODE are mutually exclusive. If the NL_CAT_JOB_MODE and NL_CAT_CTYPE_MODE flags are both set in the oflag parameter, the catopen() function will fail with a return value of CATD_ERR.
If you want the catalog messages to be converted to the
job CCSID before they are returned by the catgets()
function,
set the parameter to NL_CAT_JOB_MODE. If you want the catalog messages
to be converted to the LC_CTYPE CCSID before they are returned by catgets()
,
set the parameter to NL_CAT_CTYPE_MODE. If you do not set the parameter
to NL_CAT_JOB_MODE or NL_CAT_CTYPE_MODE, the messages are returned
without conversion and are in the CCSID of the message file.
catclose()
. If
the LC_MESSAGES locale category is changed, it might invalidate existing
open message catalogs. Return Value
If the message catalog is opened
successfully, then a valid catalog descriptor is returned. If catopen()
is
unsuccessful, then it returns CATD_ERR ((nl_catd)-1).
catopen()
function
might fail under the following conditions, and the value of errno
can be set to: - EACCES
- Insufficient authority to read the message catalog specified, or to search the component of the path prefix of the message catalog specified.
- ECONVERT
- A conversion error occurred.
- EMFILE
- NL_MAXOPEN message catalogs are currently open.
- ENAMETOOLONG
- The length of the path name of the message catalog exceeds PATH_MAX, or a path name component is longer than NAME_MAX.
- ENFILE
- Too many files are currently open in the system.
- ENOENT
- The message catalog does not exist, or the name argument points to an empty string.
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);
}
}