catopen(3)						     Library Functions Manual							catopen(3)

NAME

       catopen, NLSPATH - Opening a message catalog

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       #include <nl_types.h>

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

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       catopen(): XSH5.0

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

PARAMETERS

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

DESCRIPTION

       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 param-
       eter and the value of the LC_MESSAGES setting. (See the i18n_intro(5) reference page for a description of LC_MESSAGES.  See the NOTES  sec-
       tion for a restriction that applies to use of the NLSPATH variable.)

       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:

       /usr/lib/nls/msg/%L/%N

       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 mycmd.cat, and the environment variables are set as  fol-
       lows:

       NLSPATH=./%N:/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%l/%N LANG=fr_BE.ISO8859-1

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

       ./mycmd.cat /usr/lib/nls/msg/fr_BE.ISO88591-1/mycmd.cat /usr/lib/nls/msg/fr/mycmd.cat

       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 application 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 descrip-
       tor. For example, the application executes a successful call to the catclose() 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.

NOTES

       [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 message 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 partic-
       ular 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
       catgets() 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
       therefore  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  avail-
       able, regardless of the encoding format supported by the catalog.

       [Tru64  UNIX]  Codeset  conversion of message catalogs is enabled by the presence of the .msg_conv-lc_message file in the /usr/share direc-
       tory. 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.alias  file.  See  iconv_intro(5)  for
       more information about how codeset conversion works.

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

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

       [Tru64  UNIX]  When  codeset conversion of messages does occur, the converted 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  allo-
       cated to converted messages for the descriptor of the catalog being closed.

RETURN VALUES

       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).

ERRORS

       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.

RELATED INFORMATION

       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 delim off

																	catopen(3)