catopen(3C) SDK R4.11 catopen(3C)
NAME
catopen, catclose - open/close a message catalog
SYNOPSIS
#include <nltypes.h>
nlcatd catopen(const char *name, int oflag);
int catclose(nlcatd catd);
DESCRIPTION
catopen opens a X/Open-style message catalog and returns a catalog
descriptor. name specifies the name of the message catalog to be
opened. If name contains a ``/'' then name specifies a pathname for
the message catalog. Otherwise, the environment variable NLSPATH is
used. If NLSPATH does not exist in the environment, or if a message
catalog cannot be opened in any of the paths specified by NLSPATH,
then the default path is used [see nltypes(5)].
The names of message catalogs, and their location in the filestore,
can vary from one system to another. Individual applications can
choose to name or locate message catalogs according to their own
special needs. A mechanism is therefore required to specify where
the catalog resides.
The NLSPATH variable provides both the location of message catalogs,
in the form of a search path, and the naming conventions associated
with message catalog files. For example:
NLSPATH=/usr/lib/nls/msg/%L/%N.cat:/usr/lib/nls/msg/%N/%L
The metacharacter % introduces a substitution field, where %L
substitutes the current setting of the locale (see below) and %N
substitutes the value of the name parameter passed to catopen. Thus,
in the above example, catopen will search in
/usr/lib/nls/msg/locale/name.cat, then in
/usr/lib/nls/msg/name/locale, for the required message catalog.
The evaluation of locale as referenced by the substitution field %L
depends on the argument oflag. When oflag is NLCATLOCALE, the
LCMESSAGES category as returned by setlocale(3C) is used to locate
the message catalog. When oflag is zero, the environment variable
LANG locates the catalog without regard to the LCMESSAGES category.
If either of these methods fails, then the default language as
defined in nltypes.h is used.
For a complete description of the metacharacters available for
NLSPATH, see environ(5).
NLSPATH will normally be set up on a system wide basis (for example,
in /etc/profile) and thus makes the location and naming conventions
associated with message catalogs transparent to both programs and
users.
catclose closes the message catalog identified by catd.
Return Values
If successful, catopen returns a message catalog descriptor for use
in subsequent calls to catgets and catclose. Otherwise catopen
returns (nlcatd)-1.
catclose returns zero if successful, otherwise -1.
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|catclose | Y Y N |
|catopen | Y Y N |
+---------+-----------------------------+
REFERENCES
catexstr(1), gencat(1), reentrant(3), catgets(3C), setlocale(3C),
environ(5), nltypes(5).
mkmsgs(1), gettxt(3C) -- AT&T-style message facilities,
Licensed material--property of copyright holder(s)