catopen() -- open a message catalog

SYNOPSIS

#include <nl_types.h>

nl_catd catopen(char *name, int oflag);

The catopen() function opens a message catalog and returns a catalog descriptor. The name parameter specifies the name of the message catalog to be opened. If name contains a /, name specifies a path name for the message catalog. Otherwise, name is used as a base file name in a search path as follows:

If the environment variable NLSPATH is set in the environment, this variable is used as the search path.

If NLSPATH does not exist in the environment, the following default search path is used, where ROOTDIR is the PTC MKS Toolkit installation directory:
```
$ROOTDIR/etc/locale/~L/~N.cat:$ROOTDIR/etc/locale/~N.cat
```
- Wherever ~N or %N appears in the search path, name is substituted for the token.
- If oflag is 0, wherever ~L or %L appears in the search path, the current setting of LANG is substituted for the token. If LANG is not set, the string "C" is substituted.
- If oflag is NL_CAT_LOCALE, wherever ~L or %L appears in the search path, the current setting for the LC_MESSAGES locale category is substituted for the token. If this setting cannot be determined, the string "C" is substituted.
- If oflag is NL_CAT_LOCALE, wherever ~l or %l appears in the search path, the language component of the LC_MESSAGES locale setting is substituted for the token. Otherwise, the token is replaced by the string "l".
- If oflag is NL_CAT_LOCALE, wherever ~t or %t appears in the search path, the territory component of the LC_MESSAGES locale setting is substituted for the token. Otherwise, the token is replaced by the string "t".
- If oflag is NL_CAT_LOCALE, wherever ~c or %c appears in the search path, the codeset component of the LC_MESSAGES locale setting is substituted for the token. Otherwise, the token is replaced by the string "c".
- Each file name generated by splitting the colon-separated path is tested, in order, until the message catalog is found or the end of the search path is reached.

Refer to setlocale() for more information on the LC_MESSAGES locale category, and components of the locale setting.

The message catalog descriptor remains valid in a process until that process, or a successful call to one of the exec() family of functions is made. A change to the setting of the LC_MESSAGES locale category does not invalidate open message catalogs.

PARAMETERS

name: Is the name of the catalog to open.
oflag: Is a flag that determines how the language name is substituted into the message catalog search path, as discussed in the DESCRIPTION section.

RETURN VALUES

Upon successful completion, catopen() returns a message catalog descriptor for use in subsequent calls to catgets() and catclose(). Otherwise catopen() returns -1 and sets errno to indicate the error:

EACCES: Search permission is denied for the component of the path prefix of the message catalog or read permission is denied for the message catalog.
EMFILE: OPEN_MAX file descriptors are currently open in the calling process.
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.
ENOMEM: Insufficient storage space is available.
ENOTDIR: A component of the path prefix of the message catalog is not a directory.

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

The NuTCRACKER Platform recognizes the tilde as well as the percent symbol as the leading character for substitution tokens, because the percent symbol is used to indicate an environment variable in the Windows command processor.

The contents of a message catalog generated on a UNIX machine are not compatible with the NuTCRACKER Platform catopen() function. For this reason, you must copy the message text source files to the machine running NuTCRACKER Platform and use the MKS Toolkit gencat utility to create the message catalog file for use with the ported application.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

catopen()
open a message catalog

Function