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 .