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 .