2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk>
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze <joey@infodrom.org>
|
|
|
|
.\" Modified 2001-12-14 aeb
|
|
|
|
.\"
|
2006-05-17 21:49:21 +00:00
|
|
|
.TH CATOPEN 3 2001-12-14 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
catopen, catclose \- open/close a message catalog
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <nl_types.h>
|
|
|
|
.sp
|
|
|
|
.BI "nl_catd catopen(const char *" name ", int " flag );
|
|
|
|
.br
|
|
|
|
.BI "int catclose(nl_catd " catalog );
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The function
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR catopen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
opens a message catalog and returns a catalog descriptor.
|
2005-10-19 14:48:35 +00:00
|
|
|
The descriptor remains valid until
|
|
|
|
.BR catclose ()
|
|
|
|
or
|
|
|
|
.BR exec ().
|
2004-11-03 13:51:07 +00:00
|
|
|
If a file descriptor is used to implement catalog descriptors
|
|
|
|
then the FD_CLOEXEC flag will be set.
|
|
|
|
.LP
|
|
|
|
The argument
|
|
|
|
.I name
|
|
|
|
specifies the name of the message catalog to be opened.
|
|
|
|
If
|
|
|
|
.I name
|
|
|
|
specifies and absolute path (i.e., contains a '/'),
|
|
|
|
then
|
|
|
|
.I name
|
|
|
|
specifies a pathname for the message catalog.
|
|
|
|
Otherwise, the environment variable
|
|
|
|
.B NLSPATH
|
|
|
|
is used with
|
|
|
|
.I name
|
|
|
|
substituted for
|
|
|
|
.B %N
|
|
|
|
(see
|
|
|
|
.BR locale (7)).
|
|
|
|
It is unspecified whether
|
|
|
|
.B NLSPATH
|
|
|
|
will be used when the process has root privileges.
|
|
|
|
If
|
|
|
|
.B 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
|
|
|
|
.B LC_MESSAGES
|
|
|
|
locale setting when the
|
|
|
|
.I flag
|
|
|
|
argument is
|
|
|
|
.B NL_CAT_LOCALE
|
|
|
|
and on the
|
|
|
|
.B LANG
|
|
|
|
environment variable when the
|
|
|
|
.I flag
|
|
|
|
argument is 0.
|
|
|
|
Changing the LC_MESSAGES part of the locale may invalidate
|
|
|
|
open catalog descriptors.
|
|
|
|
.LP
|
|
|
|
The
|
|
|
|
.I flag
|
|
|
|
argument to
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR catopen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is used to indicate the source for the language to use.
|
|
|
|
If it is set to
|
|
|
|
.B NL_CAT_LOCALE
|
|
|
|
then it will use the current locale setting for
|
|
|
|
.BR LC_MESSAGES .
|
|
|
|
Otherwise it will use the
|
|
|
|
.B LANG
|
|
|
|
environment variable.
|
|
|
|
.LP
|
|
|
|
The function
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR catclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
closes the message catalog identified by
|
|
|
|
.IR catalog .
|
|
|
|
It invalidates any subsequent references to the message catalog
|
|
|
|
defined by
|
|
|
|
.IR catalog .
|
|
|
|
.LP
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
The function
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR catopen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns a message catalog descriptor of type
|
|
|
|
.I nl_catd
|
|
|
|
on success.
|
|
|
|
On failure, it returns (nl_catd) \-1
|
|
|
|
and sets
|
2004-11-10 17:11:31 +00:00
|
|
|
.I errno
|
2004-11-03 13:51:07 +00:00
|
|
|
to indicate the error. The possible error values include all
|
|
|
|
possible values for the
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR open ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call.
|
|
|
|
.LP
|
|
|
|
The function
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR catclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns 0 on success, or \-1 on failure.
|
|
|
|
.SH ENVIRONMENT
|
|
|
|
.TP
|
|
|
|
.B LC_MESSAGES
|
|
|
|
May be the source of the LC_MESSAGES locale setting, and thus
|
|
|
|
determine the language to use if
|
|
|
|
.I flag
|
|
|
|
is set to
|
|
|
|
.BR NL_CAT_LOCALE .
|
|
|
|
.TP
|
|
|
|
.B LANG
|
|
|
|
The language to use if
|
|
|
|
.I flag
|
|
|
|
is 0.
|
|
|
|
.SH NOTES
|
2006-08-03 13:57:30 +00:00
|
|
|
The above is the POSIX.1-2001 description.
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
|
|
|
.IR /usr/share/locale .
|
|
|
|
.SH "NOTES FOR LIBC4 AND LIBC5"
|
|
|
|
These functions are available for Linux since libc 4.4.4c.
|
|
|
|
In the case of linux libc4 and libc5, the catalog descriptor
|
|
|
|
.I nl_catd
|
2005-10-20 15:11:10 +00:00
|
|
|
is a
|
|
|
|
.BR mmap ()'ed
|
|
|
|
area of memory and not a file descriptor.
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
|
|
|
.I flag
|
|
|
|
argument to
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR catopen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
should be either
|
|
|
|
.B MCLoadBySet
|
|
|
|
(=0) or
|
|
|
|
.B 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
|
|
|
|
.BR catopen ()
|
|
|
|
to load the entire catalog into memory.
|
|
|
|
The default search path varies, but usually looks at a number of places below
|
|
|
|
.I /etc/locale
|
|
|
|
and
|
|
|
|
.IR /usr/lib/locale .
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:30 +00:00
|
|
|
POSIX.1-2001.
|
|
|
|
.\" In XPG 1987, Vol. 3 it says:
|
|
|
|
.\" .I "The flag argument of catopen is reserved for future use"
|
|
|
|
.\" .IR "and should be set to 0" .
|
2004-11-03 13:51:07 +00:00
|
|
|
It is unclear what the source was for the constants MCLoadBySet
|
|
|
|
and MCLoadAll.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR catgets (3),
|
|
|
|
.BR setlocale (3)
|