catopen(3C) 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 message catalog and returns a catalog descriptor.
name specifies the name to be used in opening the message catalog.
name contains a / then name specifies a pathname for the message cata-
log. 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)]. This default may be affected by the setting
of LCMESSAGES if the value of oflag is NLCATLOCALE, or the LANG
environment variable if oflag is 0.
A message catalogue descriptor remains valid in a process until that
process closes it, or a successful call to one of the exec functions.
A change in the setting of the LCMESSAGES category may invalidate
existing open catalogues.
The names of message catalogs, and their location in the filestore,
differ 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 for specifying exactly 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=/nlslib/%L/%N.cat:/nlslib/%N/%L
The metacharacter % introduces a substitution field, where %L substi-
tutes the current setting of the LANG environment variable (see fol-
lowing section), and %N substitutes the value of the name parameter
passed to catopen(). Thus, in the above example, catopen() will search
in /nlslib/$LANG/name.cat, then in /nlslib/name/$LANG, for the
required message catalog.
NLSPATH will normally be set up on a system wide basis (e.g., in
/etc/profile) and thus makes the location and naming conventions asso-
ciated with message catalogs transparent to both programs and users.
Page 1 Reliant UNIX 5.44 Printed 11/98
catopen(3C) catopen(3C)
The full set of metacharacters is:
%N The value of the name parameter passed to catopen()
%L The value of LANG.
%l The value of the language element of LANG.
%t The value of the territory element of LANG.
%c The value of the codeset element of LANG.
%% A single %.
The LANG environment variable provides the ability to specify the
user's requirements for native languages, local customs and character
set, as an ASCII string in the form:
LANG=language[_territory[.codeset]]
A user who speaks German as it is spoken in Austria and has a terminal
which operates in ISO 8859/1 codeset, would want the setting of the
LANG variable to be:
LANG=DeA.88591
With this setting it should be possible for that user to find any
relevant message catalogs, should they exist.
Should the LANG variable not be set then the value of LCMESSAGES as
returned by setlocale is used. If this is NULL then the default path
as defined in nltypes is used.
If the value of the oflag argument is 0, the LANG environment variable
is used to locate the catalogue without regard to the LCMESSAGES
category. If the oflag argument is NLCATLOCALE, the LCMESSAGES
category is used to locate the message catalogue.
catclose() closes the message catalog identified by catd.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The catopen() function may fail if:
EACCES Search permission is denied for the component of the
path prefix of the message catalogue or read permission
is denied for the message catalogue.
EMFILE OPENMAX file descriptors are currently open in the cal-
ling process.
Page 2 Reliant UNIX 5.44 Printed 11/98
catopen(3C) catopen(3C)
ENAMETOOLONG The length of the pathname of the message catalogue
exceeds PATHMAX, or a pathname component is longer than
NAMEMAX.
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATHMAX.
ENFILE Too many files are currently open in the system.
ENOENT The message catalogue does not exist or the name argu-
ment points to an empty string.
ENOMEM Insufficient storage space is available.
ENOTDIR A component of the path prefix of the message catalogue
is not a directory.
The catclose() function may fail if:
EBADF The catalogue descriptor is not valid.
EINTR The catclose() function was interrupted by a signal.
RESULT
If successful, catopen() returns a message catalog descriptor for use
on subsequent calls to catgets() and catclose(). Otherwise catopen()
returns (nlcatd)-1.
catclose() returns 0 if successful, otherwise -1.
NOTES
Some implementations of catopen() use malloc() to allocate space for
internal buffer areas. The catopen() function may fail if there is
insufficient storage space available to accommodate these buffers.
Portable applications must assume that message catalogue descriptors
are not valid after a call to one of the exec functions.
Application writers should be aware that guidelines for the location
of message catalogues have not yet been developed. Therefore they
should take care to avoid conflicting with catalogues used by other
applications and the standard utilities.
SEE ALSO
catgets(3C), setlocale(3C), environ(5), fcntl(5), nltypes(5).
Page 3 Reliant UNIX 5.44 Printed 11/98