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
       IEEE Std 1003.1-2001,  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 IEEE Std 1003.1-2001,
       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 {OPEN_MAX} file descriptors are currently open in the calling process.

       ENAMETOOLONG
              The  length  of  a  pathname  of the message catalog exceeds {PATH_MAX} or a pathname component is
              longer than {NAME_MAX}.

       ENAMETOOLONG
              Pathname resolution of a symbolic link  produced  an  intermediate  result  whose  length  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 is not 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  writers  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 IEEE Std 1003.1-2001, <fcntl.h>, <nl_types.h>,
       the Shell and Utilities volume of IEEE Std 1003.1-2001

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications Issue 6, Copyright (C) 2001-2003 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 .

IEEE/The Open Group                                   2003                                            CATOPEN(P)