catopen(3)		    Library Functions Manual		      catopen(3)

NAME
     catopen, catclose - open/close a message catalog

LIBRARY
     Standard C library (libc, -lc)

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 de-
     scriptor.	The descriptor remains valid until catclose() or execve(2).   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 an absolute path (i.e., contains a '/'), then name speci-
     fies  a pathname for the message catalog.	Otherwise, the environment vari-
     able NLSPATH is used with name substituted for %N (see locale(7)).	  It  is
     unspecified  whether  NLSPATH will be used when the process has root privi-
     leges.  If NLSPATH does not exist in the environment, or if a message cata-
     log cannot be opened in any of the paths specified by it, then an implemen-
     tation 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 lan-
     guage 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 environ-
     ment variable.

     The function catclose() closes the message catalog identified  by	catalog.
     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(2) 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 deter-
	    mine the language to use if flag is set to NL_CAT_LOCALE.

     LANG   The language to use if flag is 0.

ATTRIBUTES
     For  an  explanation  of the terms used in this section, see attributes(7).
     allbox; lbx lb lb l l l.  Interface Attribute Value T{ catopen()
     T}	  Thread safety	  MT-Safe env T{ catclose() T}	 Thread safety	MT-Safe

VERSIONS
     The above is the POSIX.1 description.  The glibc value for NL_CAT_LOCALE is
     1.	 The default path varies, but usually looks at a number of places  below
     /usr/share/locale.

STANDARDS
     POSIX.1-2008.

HISTORY
     POSIX.1-2001.

SEE ALSO
     catgets(3), setlocale(3)

Linux man-pages 6.18		   2026-02-08			      catopen(3)