catopen(3C)

catopen, catclose -- open/close a message catalog

Synopsis

   #include <nl_types.h>
   
   nl_catd catopen(const char name, int oflag);
   

   int catclose(nl_catd catd);

Description

catclose- close a message catalogue

catopen opens a 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 nl_types(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=/nlslib/%L/%N.cat:/nlslib/%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 /nlslib/locale/name.cat, then in /nlslib/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 NL_CAT_LOCALE, the LC_MESSAGES 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 LC_MESSAGES category. If either of these methods fails, then the default language as defined in nl_types.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 (nl_catd)-1.

catclose returns zero if successful, otherwise -1.

Security considerations

For processes that have gained privilege, message catalogs without general read permission will not be accepted by the localization code. This prevents malicious users from gaining access to protected system files through internationalized system routines.

References

catgets(3C), environ(5), nl_types(5), setlocale(3C)