PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       catopen — open a message catalog

SYNOPSIS

       #include <nl_types.h>

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

DESCRIPTION

       The  catopen()  function  shall  open a message catalog and return a message catalog descriptor. The name
       argument specifies the name of the message catalog to be opened.  If  name  contains  a  '/',  then  name
       specifies  a  pathname  for the message catalog. Otherwise, the environment variable NLSPATH is used with
       name substituted for the %N conversion specification (see the Base Definitions  volume  of  POSIX.1‐2017,
       Chapter  8, Environment Variables); if NLSPATH exists in the environment when the process starts, then if
       the process has appropriate privileges, the behavior of catopen() is undefined. If NLSPATH does not exist
       in the environment, or if a message catalog cannot be  found  in  any  of  the  components  specified  by
       NLSPATH,  then  an implementation-defined default path shall be used. This default may be affected by the
       setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE, or the LANG environment variable if  oflag
       is 0.

       A  message  catalog  descriptor  shall  remain  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 catalogs.

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

       If the value of the oflag argument is 0, the LANG environment variable is  used  to  locate  the  catalog
       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 catalog (see the Base Definitions volume of POSIX.1‐2017,  Section
       8.2, Internationalization Variables).

RETURN VALUE

       Upon  successful  completion,  catopen()  shall return a message catalog descriptor for use on subsequent
       calls to catgets() and catclose().  Otherwise, catopen() shall return  (nl_catd)  -1  and  set  errno  to
       indicate the error.

ERRORS

       The catopen() function may fail if:

       EACCES Search  permission  is  denied for the component of the path prefix of the message catalog or read
              permission is denied for the message catalog.

       EMFILE All file descriptors available to the process are currently open.

       ENAMETOOLONG
              The length of a component of a pathname is longer than {NAME_MAX}.

       ENAMETOOLONG
              The length of a pathname exceeds {PATH_MAX}, or pathname resolution of a symbolic link produced an
              intermediate result with a length that exceeds {PATH_MAX}.

       ENFILE Too many files are currently open in the system.

       ENOENT The message catalog does not exist or the name argument points to an empty string.

       ENOMEM Insufficient storage space is available.

       ENOTDIR
              A component of the path prefix of the message catalog names an existing file  that  is  neither  a
              directory  nor  a symbolic link to a directory, or the pathname of the message catalog contains at
              least one non-<slash> character and ends with one or more trailing <slash> characters and the last
              pathname component names an existing file that is neither a directory nor a  symbolic  link  to  a
              directory.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       Some implementations of catopen() use malloc() to allocate space for internal buffer areas. The catopen()
       function may fail if there is insufficient storage space available to accommodate these buffers.

       Conforming applications must assume that message catalog descriptors are not valid after a call to one of
       the exec functions.

       Application  developers should be aware that guidelines for the location of message catalogs have not yet
       been developed. Therefore they should take  care  to  avoid  conflicting  with  catalogs  used  by  other
       applications and the standard utilities.

       To be sure that messages produced by an application running with appropriate privileges cannot be used by
       an attacker setting an unexpected value for NLSPATH in the environment to confuse a system administrator,
       such  applications  should use pathnames containing a '/' to get defined behavior when using catopen() to
       open a message catalog.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       catclose(), catgets()

       The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, <fcntl.h>, <nl_types.h>,

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard
       for Information  Technology  --  Portable  Operating  System  Interface  (POSIX),  The  Open  Group  Base
       Specifications  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics
       Engineers, Inc and The Open Group.  In the event of any discrepancy between this version and the original
       IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee  document.
       The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any  typographical  or formatting errors that appear in this page are most likely to have been introduced
       during  the  conversion  of  the  source  files  to  man  page  format.  To  report  such   errors,   see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                                   2017                                       CATOPEN(3POSIX)