Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
catopen(3C)		 Standard C Library Functions		   catopen(3C)

       catopen,	catclose - open/close a	message	catalog

       #include	<nl_types.h>

       nl_catd catopen(const char *name, int oflag);

       int catclose(nl_catd catd);

       The  catopen()  function	 opens a message catalog and returns a message
       catalog descriptor. name	specifies the name of the message  catalog  to
       be  opened.  If	name  contains	a "/", then  name specifies a complete
       pathname	for the	message	catalog; otherwise, the	 environment  variable
       NLSPATH	is used	and  /usr/lib/locale/locale/LC_MESSAGES	must exist. If
       NLSPATH does not	exist in the environment, or if	a message catalog can-
       not  be	opened	in any of the paths specified by NLSPATH, then the de-
       fault path /usr/lib/locale/locale/LC_MESSAGES is	used. In the  "C"  lo-
       cale,   catopen()  will	always	succeed	 without  checking the default
       search path.

       The names of message catalogs and their location	in the filesystem  can
       vary  from one system to	another. Individual applications can choose to
       name or locate message catalogs according to their own special needs. A
       mechanism is therefore required to specify where	the catalog resides.

       The NLSPATH variable provides both the location of message catalogs, in
       the form	of a search path, and the naming conventions  associated  with
       message catalog files.  For example:


       The  metacharacter  % introduces	a substitution field, where %L substi-
       tutes the current setting of either the LANG environment	 variable,  if
       the  value of oflag is  0, or the LC_MESSAGES category, if the value of
       oflag is	 NL_CAT_LOCALE,	and  %N	substitutes the	value of the name  pa-
       rameter passed to catopen(). Thus, in the above example,	catopen() will
       search  in   /nlslib/$LANG/,  if	 oflag	is  0,	or   in	  /nl-
       slib/{LC_MESSAGES}/, if oflag is	NL_CAT_LOCALE.

       The NLSPATH variable will normally be set up on a system	wide basis (in
       /etc/profile) and thus makes the	location and naming conventions	 asso-
       ciated with message catalogs transparent	to both	programs and users.

       The full	set of metacharacters is:

       %N	The value of the name parameter	passed to catopen().

       %L	The value of LANG or LC_MESSAGES.

       %l	The value of the language element of LANG or LC_MESSAGES.

       %t	The value of the territory element of LANG or LC_MESSAGES.

       %c	The value of the codeset element of LANG or LC_MESSAGES.

       %%	A single %.

       The  LANG  environment  variable	 provides  the	ability	to specify the
       user's requirements for native languages, local customs	and  character
       set, as an ASCII	string in the form


       A  user who speaks German as it is spoken in Austria and	has a terminal
       which operates in ISO 8859/1 codeset, would want	 the  setting  of  the
       LANG variable to	be


       With this setting it should be possible for that	user to	find any  rel-
       evant catalogs should they exist.

       Should the LANG variable	not be set, the	value of  LC_MESSAGES  as  re-
       turned  by  setlocale()	is used.  If this is NULL, the default path as
       defined in <nl_types.h> is used.

       A message catalogue descriptor remains 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	catalogues.

       If  a  file  descriptor is used to implement message catalogue descrip-
       tors, the FD_CLOEXEC flag will be set; see <fcntl.h>.

       If the value of oflag argument is 0, the	 LANG environment variable  is
       used  to	 locate	the catalogue 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 catalogue.

       The  catclose() function	closes the message catalog identified by catd.
       If a file descriptor is used to implement the type nl_catd,  that  file
       descriptor will be closed.

       Upon  successful	 completion,  catopen()	 returns a message catalog de-
       scriptor	for use	on  subsequent calls  to   catgets()  and  catclose().
       Otherwise it returns (nl_catd) -1.

       Upon  successful	completion, catclose() returns 0. Otherwise it returns
       -1 and sets errno to indicate the error.

       The catopen() function may fail if:

       EACCES	       Search permission is denied for the  component  of  the
		       path prefix of the message catalogue or read permission
		       is denied for the message catalogue.

       EMFILE	       There are OPEN_MAX file descriptors currently  open  in
		       the calling process.

       ENAMETOOLONG    The length of the pathname of the message catalogue ex-
		       ceeds PATH_MAX, or a pathname component is longer  than

       ENAMETOOLONG    Pathname	 resolution of a symbolic link produced	an in-
		       termediate result whose length exceeds PATH_MAX.

       ENFILE	       Too many	files are currently open in the	system.

       ENOENT	       The message catalogue does not exist or the name	 argu-
		       ment points to an empty string.

       ENOMEM	       Insufficient storage space is available.

       ENOTDIR	       A component of the path prefix of the message catalogue
		       is not a	directory.

       The catclose() function may fail	if:

       EBADF	       The catalogue descriptor	is not valid.

       EINTR	       The catclose() function was interrupted by a signal.

       The catopen() and catclose() functions can be  used  safely  in	multi-
       threaded	 applications, as long as setlocale(3C)	is not being called to
       change the locale.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |MT-Safe			   |

       gencat(1), catgets(3C), gettext(3C), nl_types.h(3HEAD),	setlocale(3C),
       attributes(5), environ(5)

SunOS 5.10			  29 Dec 1996			   catopen(3C)


Want to link to this manual page? Use this URL:

home | help