catopen - open a message catalogue
#include <nl_types.h>
nl_catd catopen(const char *name, int oflag);
The catopen() function opens a message catalogue and returns a message catalogue descriptor. The name argument specifies the name of the message catalogue to be opened. If name contains a "/", then name specifies a complete name for the message catalogue. Otherwise, the environment variable is used with name substituted for %N (see the Environment Variables specification). If does not exist in the environment, or if a message catalogue cannot be found in any of the components specified by NLSPATH, then an implementation-dependent default path is used. This default may be affected by the setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE, or the environment variable if oflag is 0.
A message catalogue descriptor remains valid in a process until that process closes it, or a successful call to one of the exec functions. A change in the setting of the LC_MESSAGES category may invalidate existing open catalogues.
If a file descriptor is used to implement message catalogue descriptors, the FD_CLOEXEC flag will be set; see <fcntl.h>.
If the value of the oflag argument is 0, the environment variable is used to locate the catalogue without regard to the LC_MESSAGES category. If the oflag argument is NL_CAT_LOCALE, the LC_MESSAGES category is used to locate the message catalogue (see the Environment Variables specification).
Upon successful completion, catopen() returns a message catalogue descriptor for use on subsequent calls to catgets() and catclose(). Otherwise catopen() returns (nl_catd ) -1 and sets errno to indicate the error.
The catopen() function may fail if:
- [EACCES]
- Search permission is denied for the component of the path prefix of the message catalogue or read permission is denied for the message catalogue.
- [EMFILE]
- {OPEN_MAX} file descriptors are currently open in the calling process.
- [ENAMETOOLONG]
- The length of the pathname of the message catalogue exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.
- [ENAMETOOLONG]
- Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.
- [ENFILE]
- Too many files are currently open in the system.
- [ENOENT]
- The message catalogue 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 catalogue is not a directory.
None.
Some implementations of catopen() use malloc() to allocate space for internal buffer areas. The catopen() function may fail if there is insufficient storage space available to accommodate these buffers.
Portable applications must assume that message catalogue descriptors are not valid after a call to one of the exec functions.
Application writers should be aware that guidelines for the location of message catalogues have not yet been developed. Therefore they should take care to avoid conflicting with catalogues used by other applications and the standard utilities.
None.
catclose(3), catgets(3), <fcntl.h>, <nl_types.h>, gencat(1) .