catopen(3)catopen(3)NAME
catopen, NLSPATH - Opening a message catalog
SYNOPSIS
#include <nl_types.h>
nl_catd catopen(
const char *name,
int oflag );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
catopen(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
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.
DESCRIPTION
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 path‐
name 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 fol‐
lows:
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 appli‐
cation 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 cat‐
close() 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.
NOTES
[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 mes‐
sage 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 cat‐
gets() 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 there‐
fore 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 avail‐
able 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 mes‐
sage 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 con‐
verted 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.
RETURN VALUES
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).
ERRORS
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.
SEE ALSO
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)