CATOPEN(N)          Linux Programmer's Manual          CATOPEN(N)



NAME
       catopen, catclose - open/close a message catalog

SYNOPSIS
       #include <nl_types.h>

       nl_catd catopen(const char *name, int flag);
       int catclose(nl_catd catalog);

DESCRIPTION
       The function catopen() opens a message catalog and returns
       a catalog descriptor.  The descriptor remains valid  until
       catclose()  or  exec().   If  a file descriptor is used to
       implement catalog descriptors  then  the  FD_CLOEXEC  flag
       will be set.

       The  argument name specifies the name of the message cata-
       log to be opened.  If name  specifies  and  absolute  path
       (i.e., contains a '/'), then name specifies a pathname for
       the message catalog.  Otherwise, the environment  variable
       NLSPATH   is  used  with  name  substituted  for  %N  (see
       locale(e)).  It is unspecified  whether  NLSPATH  will  be
       used  when  the  process  has root privileges.  If NLSPATH
       does not exist in the environment, or if a message catalog
       cannot be opened in any of the paths specified by it, then
       an implementation  defined  path  is  used.   This  latter
       default  path may depend on the LC_MESSAGES locale setting
       when the flag argument is NL_CAT_LOCALE and  on  the  LANG
       environment  variable when the flag argument is 0.  Chang-
       ing the LC_MESSAGES part of the locale may invalidate open
       catalog descriptors.

       The  flag  argument  to  catopen() is used to indicate the
       source  for  the  language  to  use.   If  it  is  set  to
       NL_CAT_LOCALE  then it will use the current locale setting
       for LC_MESSAGES.  Otherwise it will use the LANG  environ-
       ment variable.

       The function catclose() closes the message catalog identi-
       fied by catalog.  It invalidates any subsequent references
       to the message catalog defined by catalog.


RETURN VALUE
       The  function catopen() returns a message catalog descrip-
       tor of type nl_catd on success.  On  failure,  it  returns
       (nl_catd)  -1  and  sets  errno to indicate the error. The
       possible error values include all possible values for  the
       open() call.

       The  function  catclose()  returns  0 on success, or -1 on
       failure.

ENVIRONMENT
       LC_MESSAGES
              May be the source of the  LC_MESSAGES  locale  set-
              ting,  and  thus  determine  the language to use if
              flag is set to NL_CAT_LOCALE.

       LANG   The language to use if flag is 0.

NOTES
       The above is the POSIX 1003.1-2001 description.  The glibc
       value  for NL_CAT_LOCALE is 1.  (Compare MCLoadAll below.)
       The default path varies, but usually looks at a number  of
       places below /usr/share/locale.

NOTES FOR LIBC4 AND LIBC5
       These functions are available for Linux since libc 4.4.4c.
       In the case of linux libc4 and libc5, the catalog descrip-
       tor  nl_catd  is a mmap()'ed area of memory and not a file
       descriptor.  The flag  argument  to  catopen()  should  be
       either  MCLoadBySet  (=0)  or  MCLoadAll (=1).  The former
       value indicates that a set  from  the  catalog  is  to  be
       loaded  when needed, whereas the latter causes the initial
       call to catopen() to load the entire catalog into  memory.
       The  default  search  path  varies, but usually looks at a
       number of places below /etc/locale and /usr/lib/locale.

CONFORMING TO
       POSIX 1003.1-2001.  In XPG 1987, Vol. 3 it says: The  flag
       argument  of catopen is reserved for future use and should
       be set to 0.  It is unclear what the source  was  for  the
       constants MCLoadBySet and MCLoadAll.

SEE ALSO
       catgets(s), setlocale(e)



GNU                         2001-12-14                 CATOPEN(N)