catopen, catclose - open/close a message catalog


     #include <nl_types.h>

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

     int catclose(nl_catd catd);


     The catopen() function opens a message catalog and returns a
     message  catalog  descriptor. name specifies the name of the
     message catalog to be opened. If name contains a  "/",  then
     name  specifies a complete pathname for the message catalog;
     otherwise, the environment  variable  NLSPATH  is  used  and
     /usr/lib/locale/locale/LC_MESSAGES  must  exist.  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 /usr/lib/locale/locale/LC_MESSAGES  is
     used.  In  the  "C"  locale,   catopen() will always succeed
     without checking the default search path.

     The names of message catalogs  and  their  location  in  the
     filesystem  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 there-
     fore 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 con-
     ventions associated with message catalog files.   For  exam-


     The metacharacter % introduces a substitution  field,  where
     %L  substitutes  the  current  setting  of  either  the LANG
     environment variable, if the value of oflag is   0,  or  the
     LC_MESSAGES   category,   if   the   value   of   oflag   is
     NL_CAT_LOCALE, and  %N substitutes the  value  of  the  name
     parameter  passed  to catopen(). Thus, in the above example,
     catopen() will search in  /nlslib/$LANG/,  if  oflag
     is  0,  or  in  /nlslib/{LC_MESSAGES}/,  if oflag is

     The NLSPATH variable will normally be set  up  on  a  system
     wide basis (in /etc/profile) and thus makes the location and
     naming conventions associated with  message  catalogs  tran-
     sparent to both programs and users.

     The full set of metacharacters is:

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

     %L    The value of LANG or LC_MESSAGES.

     %l    The  value  of  the  language  element  of   LANG   or

     %t    The  value  of  the  territory  element  of  LANG   or

     %c    The  value  of  the  codeset  element   of   LANG   or

     %%    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


     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


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

     Should  the  LANG  variable  not  be  set,  the   value   of
     LC_MESSAGES  as returned by setlocale() is used.  If this is
     NULL, the default path as defined in <nl_types.h> is used.

     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
     LC_MESSAGES  category  may  invalidate existing open catalo-

     If a file descriptor is used to implement message  catalogue
     descriptors, the FD_CLOEXEC flag will be set; see <fcntl.h>.

     If the value of oflag argument is 0, the   LANG  environment
     variable  is  used to locate the catalogue without regard to
     the   LC_MESSAGES  category.   If  the  oflag  argument   is
     NL_CAT_LOCALE,  the  LC_MESSAGES  category is used to locate
     the message catalogue.

     The catclose() function closes the message  catalog  identi-
     fied  by catd. If a file descriptor is used to implement the
     type nl_catd, that file descriptor will be closed.


     Upon successful  completion,  catopen()  returns  a  message
     catalog  descriptor  for  use  on  subsequent calls to  cat-
     gets() and catclose(). Otherwise it returns (nl_catd) -1.

     Upon successful completion, catclose() returns 0.  Otherwise
     it returns -1 and sets errno to indicate the error.


     The catopen() function may fail if:

           Search permission is denied for the component  of  the
           path  prefix  of the message catalogue or read permis-
           sion is denied for the message catalogue.

           There are OPEN_MAX file descriptors currently open  in
           the calling process.

           The length of the pathname of  the  message  catalogue
           exceeds  PATH_MAX,  or  a pathname component is longer
           than NAME_MAX.

           Pathname resolution of a  symbolic  link  produced  an
           intermediate result whose length exceeds PATH_MAX.

           Too many files are currently open in the system.

           The message catalogue does not exist or the name argu-
           ment points to an empty string.

           Insufficient storage space is available.

           A component of the path prefix of the message  catalo-
           gue 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.


     The catopen() and catclose() functions can be used safely in
     multithreaded  applications, as long as setlocale(3C) is not
     being called to change the locale.


     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Interface Stability         | Standard                    |
    | MT-Level                    | MT-Safe                     |


     gencat(1),   catgets(3C),   gettext(3C),    nl_types(3HEAD),
     setlocale(3C), attributes(5), environ(5)

Man(1) output converted with man2html