catopen(3) — Subroutines
NAME
catopen − Opens a specified message catalog
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <nl_types.h> nl_catd catopen(
const char ∗name,
int oflag);
PARAMETERS
nameSpecifies the catalog file to open.
oflagSpecify the constant NL_CAT_LOCALE to open the message catalog for the locale set for the LC_MESSAGES variable; using NL_CAT_LOCALE conforms to the XPG4 standard. You can specify 0 (zero) for compatibility with XPG3; when oflag is set to zero, the locale set for the LANG variable determines the message catalog locale.
DESCRIPTION
The catopen() function opens a specified message catalog and returns a catalog descriptor that is used to retrieve messages from the catalog.
The name parameter specifies the name of the message catalog to be opened. If name contains a / (slash), then name specifies a full pathname for the message catalog. Otherwise, the environment variable NLSPATH is used with substitutions based on the value of the name parameter and the value of the LC_MESSAGES locale category. NLSPATH is a colon-separated list of pathnames. The catopen() function makes variable substitutions in each pathname and attempts to open the specified catalog. If the open succeeds, it returns the catalog descriptor for that catalog. If the open does not succeed, the catopen() function attempts to open the next pathname in the value of the NLSPATH environment variable.
If NLSPATH does not exist in the environment, then the following system default for NLSPATH is used:
/usr/lib/nls/msg/%L/%N
If no message catalog can be opened in any of the components specified by NLSPATH, then catopen() returns a value of -1 cast to (nl_catd). This is not a valid catalog descriptor and causes subsequent calls to catgets() to return a pointer to the default message string.
The meaning of each variable in the NLSPATH environment variable is as follows:
%NThe value passed in the name parameter.
%LThe current locale name defined for the LC_MESSAGES category, for example, fr_BE.ISO8859-1.
%lThe language element of the current locale name, for example, fr.
%tThe territory element from the current locale name, for example, BE.
%cThe code set element from the current locale name, for example, ISO8859-1.
%%A single % (percent sign) character.
For example, if the catopen() function specifies a catalog with the name mycmd.cat, and the environment variables are set as follows:
NLSPATH=../%N:/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%l/%N
LANG=fr_BE.ISO8859-1
then the application searches for the catalog in the following order:
../mycmd.cat
/usr/lib/nls/msg/fr_BE.ISO88591-1/mycmd.cat
/usr/lib/nls/msg/fr/mycmd.cat
The setlocale() function sets the value of the LC_MESSAGES category based on the values of the parameters to setlocale() and on the values of the LC_MESSAGES, LANG, and LC_ALL environment variables. The application program must call setlocale() to set the LC_MESSAGES category before calling catopen().
NOTES
The message catalog is not opened until the first catgets call that refers to the catalog. Therefore, the overhead associated with opening the catalog file:
•Does not affect the speed of program startup
•Is eliminated altogether if the catalog is not used during a particular program execution cycle
Because the operation of opening the message catalog is deferred, the catopen() function always returns a valid catalog descriptor and sets errno for a very limited number of conditions. Therefore, you cannot directly determine if the catalog open succeeds. You can indirectly check if the catalog open succeeds by comparing the address of the string that the catgets() function returns with the address of the default string. If the catgets() function returns the default string, then either the catalog open failed or the catalog does not contain the requested message.
AES Support Level:
Trial use.
RETURN VALUES
When successful, the catopen() function returns a catalog descriptor that can be used in calls to the catgets() and catclose() functions. When the catopen() function does not succeed, it returns a value of -1 cast to (nl_catd).
ERRORS
If any of the following conditions occur, the catopen() function sets errno to the corresponding value. See the NOTES section for information on the impact of deferred open.
[EINTR]A signal was caught during the function.
[ENAMETOOLONG]
The length of the path of the file exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
[ENOMEM]Insufficient storage space is available.
RELATED INFORMATION
Functions: catgets(3), catclose(3), setlocale(3).