Index for Section 3

Alphabetical listing for C

Bottom of page

catopen(3)
NAME
  catopen, NLSPATH - Opening a message catalog

SYNOPSIS
  #include <nl_types.h>

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

LIBRARY
  Standard C Library (libc)

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
  name
      Specifies the message catalog to open.

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

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

  %N  The value passed in the name parameter.

  %L  The current locale name defined for the LC_MESSAGES category, for
      example, fr_BE.ISO8859-1.

  %l  The language element of the current locale name, for example, fr.

  %t  The territory element from the current locale name, for example, BE.

  %c  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:

       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 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 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
       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 .msg_conv-lc_message 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:

  alternate_lc_message
      Is the locale for which message catalogs are available.

  from-codeset
      Is the codeset of the message catalogs for that locale.

  to-codeset
      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 .msg_conv-* files for the
  .UTF-8 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 .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 allocated 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:

  [ENOENT]
      The name argument points to an empty string.

  [ENOMEM]
      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
  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

Index for Section 3

Alphabetical listing for C

Top of page