catopen() — Open a message catalog
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4 |
both |
Format
#define _XOPEN_SOURCE
#include <nl_types.h>
nl_catd catopen(const char *name, int oflag);
General description
The catopen() function opens a message catalog and returns a message catalog descriptor. The name argument specifies the name of the message catalog to be opened. If name contains a "/", then name specifies a complete name for the message catalog. Otherwise, the environment variable NLSPATH is used with name substituted for %N (see the XBD specification, topic Environment Variables). If NLSPATH does not exist in the environment, or if a message catalog cannot be found in any of the components specified by NLSPATH, then the default path of "/usr/lib/nls/msg/%L/%N" is used. The "%L" component of this default path is replaced by the setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE, or the LANG environment variable if oflag is 0. A change in the setting of the LANG or LC_MESSAGES will have no effect on existing open catalogs.
A message catalog descriptor remains valid in a process until that process closes it, or a successful call to one of the exec functions. When a message catalog is opened the FD_CLOEXEC flag will be set. See fcntl() — Control open file descriptors. Portable applications must assume that message catalog descriptors are not valid after a call to one of the exec functions.
If a catalog is opened more than once in the same process, a use count is incremented. When the use count reaches zero, by using catclose() to close the catalog, then the file descriptor for that catalog is closed.
Returned value
If successful, catopen() returns a message catalog descriptor for use on subsequent calls to catgets() and catclose().
- Error Code
- Description
- 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.