catopen, NLSPATH - Opening a message catalog
#include <nl_types.h>
nl_catd catopen(
const char *name,
int oflag );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
catopen(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the message catalog to open. Specify the constant
NL_CAT_LOCALE to open the message catalog for the
locale set for the LC_MESSAGES variable; using
NL_CAT_LOCALE conforms to the Issue 4 and higher issues of
the XSH specification. You can specify 0 (zero) for compatibility
with XSH Issue 3; when oflags is set to zero,
the locale set for the LANG variable determines the message
catalog locale.
The catopen() function opens a specified message catalog
and returns a catalog descriptor that is used by the catgets()
function to retrieve messages from the catalog.
The name parameter specifies the name of the message catalog
to be opened. If name contains a / (slash), then name
specifies a full pathname for the message catalog. Otherwise,
the environment variable NLSPATH is used with substitutions
based on the value of the name parameter and
the value of the LC_MESSAGES setting. (See the
i18n_intro(5) reference page for a description of LC_MESSAGES.
See the NOTES section for a restriction that
applies to use of the NLSPATH variable.)
NLSPATH is a colon-separated list of pathnames. The
catopen() function makes variable substitutions in each
pathname and attempts to open the specified catalog. If
the open operation succeeds, the function returns the catalog
descriptor for that catalog. If the open operation
does not succeed, the function attempts to open the next
pathname in the value of the NLSPATH environment variable.
If NLSPATH does not exist in the environment, then the
function uses the following system default for NLSPATH:
/usr/lib/nls/msg/%L/%N
Note that current industry standards do not specify the
location of message catalogs, so application developers
should consider this default to be platform specific.
If no message catalog can be opened in any of the components
specified by NLSPATH, then catopen() returns a value
of -1 cast to (nl_catd). This is not a valid catalog
descriptor and causes subsequent calls to catgets() to
return a pointer to the default message string.
The meaning of each variable in the NLSPATH environment
variable is as follows: The value passed in the name
parameter. The current locale name defined for the
LC_MESSAGES category, for example, fr_BE.ISO8859-1. The
language element of the current locale name, for example,
fr. The territory element from the current locale name,
for example, BE. The code set element from the current
locale name, for example, ISO8859-1. A single % (percent
sign) character.
For example, assume that the catopen() function specifies
a catalog with the name mycmd.cat, and the environment
variables are set as follows:
NLSPATH=./%N:/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%l/%N
LANG=fr_BE.ISO8859-1
Under these settings, the application searches for the
catalog in the following order:
./mycmd.cat
/usr/lib/nls/msg/fr_BE.ISO88591-1/mycmd.cat
/usr/lib/nls/msg/fr/mycmd.cat
The setlocale() function sets the value of the LC_MESSAGES
category based on the values of the parameters to setlocale()
and on the values of the LC_MESSAGES, LANG, and
LC_ALL environment variables. The application program must
call setlocale() to set the LC_MESSAGES category before
calling catopen().
The descriptor for a message catalog remains valid in a
process until one of the following occurs: The process
closes the catalog descriptor. For example, the application
executes a successful call to the catclose() function.
The application executes a successful call to one
of the exec() functions.
In addition, a change in the setting of LC_MESSAGES may
invalidate descriptors for catalogs that are currently
open.
[Tru64 UNIX] When running in a process whose effective
user ID (set through the setuid() call) is root, the
catopen() function ignores the NLSPATH setting and
searches for message catalogs by using the default path
/usr/lib/nls/msg/%L/%N. Therefore, if a program uses the
setuid() call to change its effective user ID to root,
either the program's message catalogs or links to its message
catalogs must reside in default directories. This
restriction exists to ensure system security. The restriction
does not apply to a program whose real user ID is
root. (In other words, the restriction does not apply to a
program that is run by a user logged in to the root
account.)
[Tru64 UNIX] A message catalog is not opened until the
first catgets call that refers to the catalog. Therefore,
the overhead associated with opening the catalog: Does not
affect the speed of program startup Is eliminated altogether
if the catalog is not used during a particular program
execution cycle
[Tru64 UNIX] Because the operation of opening the message
catalog is deferred, the catopen() function sets errno for
a very limited number of conditions. Therefore, applications
cannot directly determine if the catalog open succeeds.
They can indirectly check if the catalog open succeeds
by comparing the address of the string that the catgets()
function returns with the address of the default
string. If the catgets() function returns the default
string, then either the catalog open failed or the catalog
does not contain the requested message.
[Tru64 UNIX] Most languages are supported by multiple
locales, each of which may use a different codeset. A
user's locale setting may therefore be appropriate for the
language in which messages are available but not in the
correct character encoding. In such cases, it is useful to
enable codeset conversion of message catalogs, so that
users can receive messages in their native language when
these are available, regardless of the encoding format
supported by the catalog.
[Tru64 UNIX] Codeset conversion of message catalogs is
enabled by the presence of the file in the /usr/share
directory. The lc_message part of this file name must correspond
to the value of the LC_MESSAGES part of the user's
locale setting. The one-line content of this file has the
following format:
alternate_lc_message from-codeset to-codeset
In this entry format: Is the locale for which message catalogs
are available. Is the codeset of the message catalogs
for that locale. Is the codeset to which messages
need to be converted (the codeset of the user's locale).
[Tru64 UNIX] The alternate_lc_message value replaces the
user's locale in the %L position of the NLSPATH setting.
The from-codeset and to-codeset values are used to find
the appropriate codeset converter. These values must
match the corresponding name segments for an available
codeset converter or aliases for those name segments as
specified in the /usr/lib/nls/loc/iconv/iconv.alias file.
See iconv_intro(5) for more information about how codeset
conversion works.
[Tru64 UNIX] The operating system supplies files for the
locales, many of which have translated message catalogs
available for *.ISO8859-1 or other encoding formats.
[Tru64 UNIX] Note that the catgets() function first looks
for a message catalog that matches the user's locale. Only
if a catalog is not found does the function check for a
file appropriate for the user's locale.
[Tru64 UNIX] When codeset conversion of messages does
occur, the converted messages remain in memory in a data
structure associated with the opened catalog's descriptor
for re-use by subsequent calls to the catgets() function.
The catclose() function frees the memory allocated to converted
messages for the descriptor of the catalog being
closed.
When successful, the catopen() function returns a catalog
descriptor that can be used in calls to the catgets() and
catclose() functions. When the catopen() function does not
succeed, it returns a value of -1 cast to (nl_catd).
If any of the following conditions occur, the catopen()
function sets errno to the corresponding value: The name
argument points to an empty string. Insufficient memory
is available.
[Tru64 UNIX] See the NOTES section for information on the
impact of deferred open and catgets(3) for additional
errors that can occur when the catalog is opened.
Functions: catgets(3), catclose(3), setlocale(3)
Commands: dspcat(1), dspmsg(1), extract(1), gencat(1),
mkcatdefs(1), strextract(1), strmerge(1), trans(1)
Others: i18n_intro(5), iconv_intro(5), l10n_intro(5),
standards(5)
Writing Software for the International Market
catopen(3)
[ Back ] |
