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 execve(2).  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 catalog 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(7)).  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.  Changing 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 environment variable.

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

RETURN VALUE

       The  function  catopen()  returns a message catalog descriptor 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(2) call.

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

ENVIRONMENT

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

       LANG   The language to use if flag is 0.

CONFORMING TO

       POSIX.1-2001.  It is unclear what  the  source  was  for  the  constants  MCLoadBySet  and
       MCLoadAll (see below).

NOTES

       The  above  is  the  POSIX.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.

   Linux notes
       These functions are available for Linux since libc 4.4.4c.  In the case of linux libc4 and
       libc5, the catalog descriptor nl_catd is a mmap(2)'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.

SEE ALSO

       catgets(3), setlocale(3)

COLOPHON

       This  page  is  part of release 3.54 of the Linux man-pages project.  A description of the
       project,    and    information    about    reporting    bugs,    can    be    found     at
       http://www.kernel.org/doc/man-pages/.