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  complete  name 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‐2008, 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‐2008, 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.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       catclose(), catgets()

       The Base Definitions volume of POSIX.1‐2008, 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, 2013 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX),  The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/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 .