huschi.net

CATOPEN(3P)                POSIX Programmer's Manual               CATOPEN(3P)
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  mes-
       sage  catalog  descriptor.  The name argument specifies the name of the
       message catalog to be opened. If name contains a '/', then name  speci-
       fies  a  complete name for the message catalog. Otherwise, the environ-
       ment variable NLSPATH is used with name substituted for the %N  conver-
       sion  specification  (see  the Base Definitions volume of POSIX.1-2008,
       Chapter 8, Environment Variables).  If NLSPATH exists in  the  environ-
       ment when the process starts, then if the process has appropriate priv-
       ileges, 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 exist-
       ing 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  cate-
       gory.  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 indi-
       cate 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 mes-
              sage 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 resolu-
              tion  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 trail-
              ing  <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 Electri-
       cal 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.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                          CATOPEN(3P)