*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> NLSPATH (3)              



NAME    [Toc]    [Back]

       catopen, NLSPATH - Opening a message catalog

SYNOPSIS    [Toc]    [Back]

       #include <nl_types.h>

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

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       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    [Toc]    [Back]

       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.

DESCRIPTION    [Toc]    [Back]

       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 pathname 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 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:


       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 follows:



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

NOTES    [Toc]    [Back]

       [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

       [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  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  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  available
       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 message 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 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 allocated to converted
 messages for the descriptor of  the  catalog  being

RETURN VALUES    [Toc]    [Back]

       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    [Toc]    [Back]

       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.

SEE ALSO    [Toc]    [Back]

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

       Writing Software for the International Market

[ Back ]
 Similar pages
Name OS Title
dspmsg Tru64 Displays a selected message from a message catalog
catgetmsg IRIX Reads a message from a message catalog
catopen NetBSD open message catalog
catclose NetBSD close message catalog
catclose OpenBSD close message catalog
catgets Tru64 Retrieve a message from a catalog
catclose Tru64 Close a specified message catalog
catclose FreeBSD close message catalog
catopen FreeBSD open message catalog
catopen OpenBSD open message catalog
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service