catclose

CATOPEN(3)							   CATOPEN(3)



NAME
       catopen, catclose - open/close a message catalog

SYNOPSIS
       #include <nl_types.h>

       nl_catd catopen(const char *name, int flag);
       int catclose(nl_catd catalog);

DESCRIPTION
       The  function  catopen() opens a message catalog and returns a catalog
       descriptor.  The descriptor remains valid until catclose() or  exec().
       If a file descriptor is used to implement catalog descriptors then the
       FD_CLOEXEC flag will be set.

       The argument name specifies the name of	the  message  catalog  to  be
       opened.	 If  name specifies and absolute path (i.e., contains a ’/’),
       then name specifies a pathname for the  message	catalog.   Otherwise,
       the  environment variable NLSPATH is used with name substituted for %N
       (see locale(7)).	 It is unspecified whether NLSPATH will be used	 when
       the  process  has  root	privileges.  If NLSPATH does not exist in the
       environment, or if a message catalog cannot be opened in	 any  of  the
       paths  specified	 by  it, then an implementation defined path is used.
       This latter default path may depend on the LC_MESSAGES locale  setting
       when  the  flag	argument is NL_CAT_LOCALE and on the LANG environment
       variable when the flag argument is 0.  Changing the  LC_MESSAGES	 part
       of the locale may invalidate open catalog descriptors.

       The  flag argument to catopen() is used to indicate the source for the
       language to use.	 If it is set to NL_CAT_LOCALE then it will  use  the
       current	locale	setting	 for  LC_MESSAGES.  Otherwise it will use the
       LANG environment variable.

       The function catclose() closes the message catalog identified by cata-
       log.   It invalidates any subsequent references to the message catalog
       defined by catalog.


RETURN VALUE
       The function catopen() returns a message catalog	 descriptor  of	 type
       nl_catd	on  success.   On  failure,  it returns (nl_catd) -1 and sets
       errno to indicate the error. The possible  error	 values	 include  all
       possible values for the open() call.

       The function catclose() returns 0 on success, or -1 on failure.

ENVIRONMENT
       LC_MESSAGES
	      May  be  the source of the LC_MESSAGES locale setting, and thus
	      determine the language to use if flag is set to  NL_CAT_LOCALE.

       LANG   The language to use if flag is 0.

NOTES
       The  above  is the POSIX 1003.1-2001 description.  The glibc value for
       NL_CAT_LOCALE is 1.  (Compare  MCLoadAll	 below.)   The	default	 path
       varies,	 but   usually	 looks	 at   a	  number   of	places	below
       /usr/share/locale.

NOTES FOR LIBC4 AND LIBC5
       These functions are available for Linux since  libc  4.4.4c.   In  the
       case  of	 linux	libc4  and libc5, the catalog descriptor nl_catd is a
       mmap()’ed area of memory and not a file descriptor.  The flag argument
       to catopen() should be either MCLoadBySet (=0) or MCLoadAll (=1).  The
       former value indicates that a set from the catalog  is  to  be  loaded
       when  needed,  whereas the latter causes the initial call to catopen()
       to load the entire catalog  into	 memory.   The	default	 search	 path
       varies,	but usually looks at a number of places below /etc/locale and
       /usr/lib/locale.

CONFORMING TO
       POSIX 1003.1-2001.  In XPG 1987, Vol. 3 it says: The flag argument  of
       catopen	is  reserved  for  future  use and should be set to 0.	It is
       unclear what the source was for the constants MCLoadBySet and  MCLoad-
       All.

SEE ALSO
       catgets(3), setlocale(3)



				  2001-12-14			   CATOPEN(3)