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
descriptor. The descriptor remains valid until catclose() or ex-
ecve(2). If a file descriptor is used to implement catalog descrip-
tors, 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
environment variable NLSPATH is used with name substituted for %N (see
locale(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
specified 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 lo-
cale may invalidate 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
determine 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 attrib-
utes(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_LO-
CALE 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.7 2023-10-31 catopen(3)
Generated by dwww version 1.16 on Tue Dec 16 14:47:07 CET 2025.