The function
catopen()
opens a message catalog and returns a catalog descriptor.
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 and absolute path (i.e., contains a aq/aq),
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 environment,
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 locale 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
catalog.
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.
CONFORMING TO
POSIX.1-2001.
It is unclear what the source was for the constants
MCLoadBySet
and
MCLoadAll
(see below).
NOTES
The above is the POSIX.1-2001 description.
The glibc value for
NL_CAT_LOCALE
is 1.
(Compare
MCLoadAll
below.)
The default path varies, but usually looks at a number of places below
/usr/share/locale.
Linux Notes
These functions are available for Linux since libc 4.4.4c.
In the case of linux libc4 and libc5, the catalog descriptor
nl_catd
is a
mmap(2)'ed
area of memory and not a file descriptor.
The
flag
argument to
catopen()
should be either
MCLoadBySet
(=0) or
MCLoadAll
(=1).
The former value indicates that a set from the catalog is to be
loaded when needed, whereas the latter causes the initial call to
catopen()
to load the entire catalog into memory.
The default search path varies, but usually looks at a number of places below
/etc/locale
and
/usr/lib/locale.
This page is part of release 3.14 of the Linux
man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://www.kernel.org/doc/man-pages/.
