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
       default path /usr/lib/locale/locale/LC_MESSAGES is  used.  In  the  "C"
       locale,	 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
       parameter  passed  to  catopen(). Thus, in the above example, catopen()
       will  search  in	  /nlslib/$LANG/,  if  oflag  is  0,   or   in
       /nlslib/{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
       returned	 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
       descriptor 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
		       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 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