catopen

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

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  ex-
       ecve(2).   If  a  file descriptor is used to implement catalog descrip-
       tors, 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 environ-
       ment, 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  lo-
       cale 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  cata-
       log.   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  at-
       tributes(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_LO-
       CALE 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 5.05 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
       https://www.kernel.org/doc/man-pages/.

GNU                               2015-08-08                        CATOPEN(3)