catopen man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

catopen(3)							    catopen(3)

       catopen, NLSPATH - Opening a message catalog

       #include <nl_types.h>

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

       Standard C Library (libc)

       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       catopen(): XSH5.0

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

       Specifies   the	 message   catalog  to	open.	Specify	 the  constant
       NL_CAT_LOCALE to open the message catalog for the locale	 set  for  the
       LC_MESSAGES  variable;  using NL_CAT_LOCALE conforms to the Issue 4 and
       higher issues of the XSH specification. You can specify	0  (zero)  for
       compatibility  with XSH Issue 3; when oflags is set to zero, the locale
       set for the LANG variable determines the message catalog locale.

       The catopen() function opens a specified message catalog and returns  a
       catalog	descriptor  that is used by the catgets() function to retrieve
       messages from the catalog.

       The name parameter specifies the name of	 the  message  catalog	to  be
       opened.	If name contains a / (slash), then name specifies a full path‐
       name for the  message  catalog.	Otherwise,  the	 environment  variable
       NLSPATH	is  used  with	substitutions  based  on the value of the name
       parameter  and  the  value  of  the  LC_MESSAGES	 setting.   (See   the
       i18n_intro(5)  reference page for a description of LC_MESSAGES. See the
       NOTES section for a restriction that applies  to	 use  of  the  NLSPATH

       NLSPATH	is a colon-separated list of pathnames. The catopen() function
       makes variable substitutions in each pathname and attempts to open  the
       specified catalog. If the open operation succeeds, the function returns
       the catalog descriptor for that catalog. If the open operation does not
       succeed,	 the  function attempts to open the next pathname in the value
       of the NLSPATH environment variable.

       If NLSPATH does not exist in the environment, then  the	function  uses
       the following system default for NLSPATH:


       Note  that  current  industry  standards do not specify the location of
       message	catalogs,  so  application  developers	should	consider  this
       default to be platform specific.

       If  no message catalog can be opened in any of the components specified
       by NLSPATH, then catopen() returns a value of  -1  cast	to  (nl_catd).
       This  is	 not a valid catalog descriptor and causes subsequent calls to
       catgets() to return a pointer to the default message string.

       The meaning of each variable in the NLSPATH environment variable is  as
       follows:	 The  value  passed in the name parameter.  The current locale
       name   defined	for   the   LC_MESSAGES	  category,    for    example,
       fr_BE.ISO8859-1.	  The language element of the current locale name, for
       example, fr.  The territory element from the current locale  name,  for
       example,	 BE.   The  code set element from the current locale name, for
       example, ISO8859-1.  A single % (percent sign) character.

       For example, assume that the catopen()  function	 specifies  a  catalog
       with  the name, and the environment variables are set as fol‐



       Under these settings, the application searches for the catalog  in  the
       following order:




       The  setlocale()	 function  sets	 the value of the LC_MESSAGES category
       based on the values of the parameters to setlocale() and on the	values
       of  the LC_MESSAGES, LANG, and LC_ALL environment variables. The appli‐
       cation program must call setlocale() to set  the	 LC_MESSAGES  category
       before calling catopen().

       The  descriptor	for a message catalog remains valid in a process until
       one of the following occurs: The process closes the catalog descriptor.
       For  example,  the  application	executes a successful call to the cat‐
       close() function.  The application executes a successful call to one of
       the exec() functions.

       In  addition,  a	 change	 in  the setting of LC_MESSAGES may invalidate
       descriptors for catalogs that are currently open.

       [Tru64 UNIX]  When running in a process whose effective	user  ID  (set
       through	the setuid() call) is root, the catopen() function ignores the
       NLSPATH setting and searches for message catalogs by using the  default
       path  /usr/lib/nls/msg/%L/%N. Therefore, if a program uses the setuid()
       call to change its effective user ID to root, either the program's mes‐
       sage  catalogs  or links to its message catalogs must reside in default
       directories. This restriction exists to	ensure	system	security.  The
       restriction does not apply to a program whose real user ID is root. (In
       other words, the restriction does not apply to a program that is run by
       a user logged in to the root account.)

       [Tru64  UNIX]   A message catalog is not opened until the first catgets
       call that refers to the catalog.	 Therefore,  the  overhead  associated
       with  opening the catalog: Does not affect the speed of program startup
       Is eliminated altogether if the catalog is not used during a particular
       program execution cycle

       [Tru64  UNIX]  Because  the operation of opening the message catalog is
       deferred, the catopen() function sets errno for a very  limited	number
       of conditions. Therefore, applications cannot directly determine if the
       catalog open succeeds. They can indirectly check if  the	 catalog  open
       succeeds	 by  comparing	the  address  of the string that the catgets()
       function returns with the address of the default string.	 If  the  cat‐
       gets()  function	 returns  the  default string, then either the catalog
       open failed or the catalog does not contain the requested message.

       [Tru64 UNIX]  Most languages are supported by multiple locales, each of
       which  may  use a different codeset. A user's locale setting may there‐
       fore be appropriate for the language in which  messages	are  available
       but  not in the correct character encoding. In such cases, it is useful
       to enable codeset conversion of message catalogs,  so  that  users  can
       receive	messages  in  their  native language when these are available,
       regardless of the encoding format supported by the catalog.

       [Tru64 UNIX]  Codeset conversion of message catalogs is enabled by  the
       presence	 of  the file in the /usr/share directory. The lc_message part
       of this file name must correspond to the value of the LC_MESSAGES  part
       of the user's locale setting. The one-line content of this file has the
       following format:

       alternate_lc_message from-codeset to-codeset

       In this entry format: Is the locale  for	 which	message	 catalogs  are
       available.  Is the codeset of the message catalogs for that locale.  Is
       the codeset to which messages need to be converted (the codeset of  the
       user's locale).

       [Tru64 UNIX]  The alternate_lc_message value replaces the user's locale
       in the %L position of the NLSPATH setting.  The	from-codeset  and  to-
       codeset	values	are  used  to  find the appropriate codeset converter.
       These values must match the corresponding name segments for  an	avail‐
       able  codeset converter or aliases for those name segments as specified
       in the /usr/lib/nls/loc/iconv/iconv.alias file. See iconv_intro(5)  for
       more information about how codeset conversion works.

       [Tru64 UNIX]  The operating system supplies files for the locales, many
       of which have translated message catalogs available for *.ISO8859-1  or
       other encoding formats.

       [Tru64  UNIX]  Note  that the catgets() function first looks for a mes‐
       sage catalog that matches the user's locale. Only if a catalog  is  not
       found  does  the	 function  check for a file appropriate for the user's

       [Tru64 UNIX]  When codeset conversion of messages does occur, the  con‐
       verted  messages	 remain	 in memory in a data structure associated with
       the opened catalog's descriptor for re-use by subsequent calls  to  the
       catgets()  function. The catclose() function frees the memory allocated
       to converted messages for the descriptor of the catalog being closed.

       When successful, the catopen() function returns	a  catalog  descriptor
       that  can  be  used in calls to the catgets() and catclose() functions.
       When the catopen() function does not succeed, it returns a value of  -1
       cast to (nl_catd).

       If  any	of the following conditions occur, the catopen() function sets
       errno to the corresponding value: The name argument points to an	 empty
       string.	Insufficient memory is available.

       [Tru64  UNIX]  See  the	NOTES section for information on the impact of
       deferred open and catgets(3) for additional errors that can occur  when
       the catalog is opened.

       Functions: catgets(3), catclose(3), setlocale(3)

       Commands:  dspcat(1),  dspmsg(1),  extract(1), gencat(1), mkcatdefs(1),
       strextract(1), strmerge(1), trans(1)

       Others: i18n_intro(5), iconv_intro(5), l10n_intro(5), standards(5)

       Writing Software for the International Market


List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net