catopen(3) Library Functions Manual catopen(3)
NAME
catopen, catclose - open/close a message catalog
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <nl_types.h>
nl_catd catopen(const char *name, int flag);
int catclose(nl_catd catalog);
DESCRIPTION
The function catopen() opens a message catalog and returns a catalog de-
scriptor. The descriptor remains valid until catclose() or execve(2).
If a file descriptor is used to implement catalog descriptors, then the
FD_CLOEXEC flag will be set.
The argument name specifies the name of the message catalog to be
opened. If name specifies an absolute path (i.e., contains a '/'), then
name specifies a pathname for the message catalog. Otherwise, the envi-
ronment variable NLSPATH is used with name substituted for %N (see lo-
cale(7)). It is unspecified whether NLSPATH will be used when the
process has root privileges. If NLSPATH does not exist in the environ-
ment, or if a message catalog cannot be opened in any of the paths spec-
ified by it, then an implementation defined path is used. This latter
default path may depend on the LC_MESSAGES locale setting when the flag
argument is NL_CAT_LOCALE and on the LANG environment variable when the
flag argument is 0. Changing the LC_MESSAGES part of the locale may in-
validate open catalog descriptors.
The flag argument to catopen() is used to indicate the source for the
language to use. If it is set to NL_CAT_LOCALE, then it will use the
current locale setting for LC_MESSAGES. Otherwise, it will use the LANG
environment variable.
The function catclose() closes the message catalog identified by cata-
log. It invalidates any subsequent references to the message catalog
defined by catalog.
RETURN VALUE
The function catopen() returns a message catalog descriptor of type
nl_catd on success. On failure, it returns (nl_catd) -1 and sets errno
to indicate the error. The possible error values include all possible
values for the open(2) call.
The function catclose() returns 0 on success, or -1 on failure.
ENVIRONMENT
LC_MESSAGES
May be the source of the LC_MESSAGES locale setting, and thus de-
termine the language to use if flag is set to NL_CAT_LOCALE.
LANG The language to use if flag is 0.
ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7).
┌────────────────────────────────────────┬───────────────┬─────────────┐
│ Interface │ Attribute │ Value │
├────────────────────────────────────────┼───────────────┼─────────────┤
│ catopen() │ Thread safety │ MT-Safe env │
├────────────────────────────────────────┼───────────────┼─────────────┤
│ catclose() │ Thread safety │ MT-Safe │
└────────────────────────────────────────┴───────────────┴─────────────┘
VERSIONS
The above is the POSIX.1 description. The glibc value for NL_CAT_LOCALE
is 1. The default path varies, but usually looks at a number of places
below /usr/share/locale.
STANDARDS
POSIX.1-2008.
HISTORY
POSIX.1-2001.
SEE ALSO
catgets(3), setlocale(3)
Linux man-pages 6.9.1 2024-05-02 catopen(3)
Generated by dwww version 1.16 on Tue Dec 16 04:28:47 CET 2025.