Opens a specified message catalog.
Standard C Library (libc.a)
#include <nl_types.h>nl_catd catopen ( CatalogName, Parameter)
const char *CatalogName;
int Parameter;
The catopen subroutine opens a specified message catalog and returns a catalog descriptor used to retrieve messages from the catalog. The contents of the catalog descriptor are complete when the catgets subroutine accesses the message catalog. The nl_catd data type is used for catalog descriptors and is defined in the nl_types.h file.
If the catalog file name referred to by the CatalogName parameter contains a leading / (slash), it is assumed to be an absolute path name. If the catalog file name is not an absolute path name, the user environment determines which directory paths to search. The NLSPATH environment variable defines the directory search path. When this variable is used, the setlocale subroutine must be called before the catopen subroutine.
A message catalog descriptor remains valid in a process until that process or a successful call to one of the exec functions closes it.
You can use two special variables, %N and %L, in the NLSPATH environment variable. The %N variable is replaced by the catalog name referred to by the call that opens the message catalog. The %L variable is replaced by the value of the LC_MESSAGES category.
The value of the LC_MESSAGES category can be set by specifying values for the LANG, LC_ALL, or LC_MESSAGES environment variable. The value of the LC_MESSAGES category indicates which locale-specific directory to search for message catalogs. For example, if the catopen subroutine specifies a catalog with the name mycmd, and the environment variables are set as follows:
NLSPATH=../%N:./%N:/system/nls/%L/%N:/system/nls/%N LANG=fr_FRthen the application searches for the catalog in the following order:
../mycmd
./mycmd
/system/nls/fr_FR/mycmd
/system/nls/mycmdIf you omit the %N variable in a directory specification within the NLSPATH environment variable, the application assumes that it defines a catalog name and opens it as such and will not traverse the rest of the search path.
If the NLSPATH environment variable is not defined, the catopen subroutine uses the default path. See the /etc/environment file for the NLSPATH default path. If the LC_MESSAGES category is set to the default value C, and the LC__FASTMSG environment variable is set to true, then subsequent calls to the catgets subroutine generate pointers to the program-supplied default text.
The catopen subroutine treats the first file it finds as a message file. If you specify a non-message file in a NLSPATH, for example, /usr/bin/ls, catopen treats /usr/bin/ls as a message catalog. Thus no messages are found and default messages are returned. If you specify /tmp in a NLSPATH, /tmp is opened and searched for messages and default messages are displayed.
| Item | Description |
|---|---|
| CatalogName | Specifies the catalog file to open. |
| Parameter | Determines the environment variable to use in locating the message catalog. If the value of the Parameter parameter is 0, use the LANG environment variable without regard to the LC_MESSAGES category to locate the catalog. If the value of the Parameter parameter is the NL_CAT_LOCALE macro, use the LC_MESSAGES category to locate the catalog. |
The catopen subroutine returns a catalog descriptor. If the LC_MESSAGES category is set to the default value C, and the LC__FASTMSG environment variable is set to true, the catopen subroutine returns a value of -1.
If the LC_MESSAGES category is not set to the default value C but the catopen subroutine returns a value of -1, an error has occurred during creation of the structure of the nl_catd data type or the catalog name referred to by the CatalogName parameter does not exist.