catopen(3C)                                                        catopen(3C)


NAME
     catopen, catclose - open/close a message catalogue

SYNOPSIS
     #include <nl_types.h>

     nl_catd catopen (const char *name, int oflag);

     int catclose (nl_catd catd);

DESCRIPTION
     catopen opens a message catalogue and returns a catalogue descriptor.
     name specifies the name of the message catalogue to be opened.  If name
     contains a ``/'' then name specifies a pathname for the message
     catalogue.  Otherwise, the environment variable NLSPATH is used.  If
     NLSPATH does not exist in the environment, or if a message catalogue
     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 catalogues, and their location in the filestore, can
     vary from one system to another.  Individual applications can choose to
     name or locate message catalogues according to their own special needs.
     A mechanism is therefore required to specify where the catalogue resides.

     The NLSPATH variable provides both the location of message catalogues, in
     the form of a search path, and the naming conventions associated with
     message catalogue 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 LANG environment variable if oflag is 0 or the
     current setting of the LC_MESSAGES category if oflag is NL_CAT_LOCALE
     (see following section), and %N substitutes the value of the name
     parameter passed to catopen.  Thus, in the above example, if oflag is 0,
     catopen will search in /nlslib/$LANG/name.cat, then in
     /nlslib/name/$LANG, for the required message catalogue.

     NLSPATH will normally be set up on a system wide basis (e.g., in
     /etc/profile) and thus makes the location and naming conventions
     associated with message catalogues transparent to both programs and
     users.

     Security dictates that catopen does not honor the NLSPATH environment
     variable for setuid and setgid programs.

     The full set of metacharacters is:

          %N   The value of the name parameter passed to catopen.


          %L   The value of LANG environment variable if oflag is 0.  The
               value of LC_MESSAGES category if oflag is NL_CAT_LOCALE.

          %l   The value of the language element of LANG environment variable
               if oflag is 0.  The value of the language element of
               LC_MESSAGES category if oflag is NL_CAT_LOCALE.

          %t   The value of the territory element of LANG environment variable
               if oflag is 0.  The value of the territory element of
               LC_MESSAGES category if oflag is NL_CAT_LOCALE.

          %c   The value of the codeset element of LANG environment variable
               if oflag is 0.  The value of the codeset element of LC_MESSAGES
               category if oflag is NL_CAT_LOCALE.

          %%   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=De_A.88591

     With this setting it should be possible for that user to find any
     relevant catalogues should they exist.

     If it still can't find the catalogue file, then the default path as
     defined in nl_types is used.

     oflag is used to locate the catalogue file. If oflag is 0, the LANG
     environment variable is used to locate it. If oflag is set to
     NL_CAT_LOCALE, the LC_MESSAGES category is used to locate the catalogue
     file.  The results of setting this field to any other value are
     undefined.

     catclose closes the message catalogue identified by catd.

SEE ALSO
     catgets(3C), setlocale(3C), environ(5), nl_types(5).

DIAGNOSTICS
     If successful, catopen returns a message catalogue descriptor for use in
     subsequent calls to catgets and catclose.  Otherwise catopen returns
     (nl_catd) -1.


     catclose returns 0 if successful, otherwise -1.


                                                                        Page 3