NAME

catopen - open a message catalogue

 SYNOPSIS

#include <nl_types.h>

nl_catd catopen(const char *name, int oflag);

 DESCRIPTION

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 NLSPATH is used with name substituted for %N (see the XBD specification, Environment Variables ). If NLSPATH 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. If NLSPATH exists in the environment when the process starts, then if the process has appropriate privileges, the behavior of catopen() is undefined. This default may be affected 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 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 LANG 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 XBD specification, Environment Variables ).

 RETURN VALUE

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.

 ERRORS

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.

 EXAMPLES

None.

 APPLICATION USAGE

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.

 FUTURE DIRECTIONS

None.

 SEE ALSO

catclose(), catgets(), <fcntl.h>, <nl_types.h>, the XCU specification, gencat.