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 an 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.

ATTRIBUTES

       For an explanation of the terms used in this section, see attributes(7).

       ┌───────────┬───────────────┬─────────────┐
       │Interface  │ Attribute     │ Value       │
       ├───────────┼───────────────┼─────────────┤
       │catopen()  │ Thread safety │ MT-Safe env │
       ├───────────┼───────────────┼─────────────┤
       │catclose() │ Thread safety │ MT-Safe     │
       └───────────┴───────────────┴─────────────┘

CONFORMING TO

       POSIX.1-2001, POSIX.1-2008.

NOTES

       The above is the POSIX.1 description.  The  glibc  value  for  NL_CAT_LOCALE  is  1.   The
       default path varies, but usually looks at a number of places below /usr/share/locale.

SEE ALSO

       catgets(3), setlocale(3)

COLOPHON

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