 |
Click this button to go to the index for this section. |
catopen(3)
NAME
catopen, NLSPATH - Opening a message catalog
LIBRARY
Standard C Library (libc.so, libc.a)
SYNOPSIS
#include <nl_types.h>
nl_catd catopen(
const char *name,
int oflag);
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
catopen(): XPG4
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
name
Specifies the message catalog to open.
oflag
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 XPG4 standard. You can specify 0 (zero) for compatibility with
XPG3; when oflag 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 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:
%N The value passed in the name parameter.
%L The current locale name defined for the LC_MESSAGES category, for
example, fr_BE.ISO8859-1.
%l The language element of the current locale name, for example, fr.
%t The territory element from the current locale name, for example, BE.
%c 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.
NOTES
[Digital] 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.)
[Digital] On DIGITAL UNIX systems, 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
[Digital] Because the operation of opening the message catalog is
deferred, the catopen() function always returns a valid catalog descriptor
and 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.
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.
[Digital] See the NOTES section for information on the impact of deferred
open.
[EINTR]
A signal was caught during the function.
[ENAMETOOLONG]
The length of the path of the file exceeds PATH_MAX, or a pathname
component is longer than NAME_MAX.
[ENOMEM]
Insufficient memory is available.
RELATED INFORMATION
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), l10n_intro(5), standards(5)
Writing Software for the International Market