GNU Info

Info Node: (libc.info)The catgets Functions

(libc.info)The catgets Functions


Next: The message catalog files Up: Message catalogs a la X/Open
Enter node , (file) or (file)node

The `catgets' function family
-----------------------------

 - Function: nl_catd catopen (const char *CAT_NAME, int FLAG)
     The `catgets' function tries to locate the message data file names
     CAT_NAME and loads it when found.  The return value is of an
     opaque type and can be used in calls to the other functions to
     refer to this loaded catalog.

     The return value is `(nl_catd) -1' in case the function failed and
     no catalog was loaded.  The global variable ERRNO contains a code
     for the error causing the failure.  But even if the function call
     succeeded this does not mean that all messages can be translated.

     Locating the catalog file must happen in a way which lets the user
     of the program influence the decision.  It is up to the user to
     decide about the language to use and sometimes it is useful to use
     alternate catalog files.  All this can be specified by the user by
     setting some environment variables.

     The first problem is to find out where all the message catalogs are
     stored.  Every program could have its own place to keep all the
     different files but usually the catalog files are grouped by
     languages and the catalogs for all programs are kept in the same
     place.

     To tell the `catopen' function where the catalog for the program
     can be found the user can set the environment variable `NLSPATH' to
     a value which describes her/his choice.  Since this value must be
     usable for different languages and locales it cannot be a simple
     string.  Instead it is a format string (similar to `printf''s).
     An example is

          /usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N

     First one can see that more than one directory can be specified
     (with the usual syntax of separating them by colons).  The next
     things to observe are the format string, `%L' and `%N' in this
     case.  The `catopen' function knows about several of them and the
     replacement for all of them is of course different.

    `%N'
          This format element is substituted with the name of the
          catalog file.  This is the value of the CAT_NAME argument
          given to `catgets'.

    `%L'
          This format element is substituted with the name of the
          currently selected locale for translating messages.  How this
          is determined is explained below.

    `%l'
          (This is the lowercase ell.) This format element is
          substituted with the language element of the locale name.
          The string describing the selected locale is expected to have
          the form `LANG[_TERR[.CODESET]]' and this format uses the
          first part LANG.

    `%t'
          This format element is substituted by the territory part TERR
          of the name of the currently selected locale.  See the
          explanation of the format above.

    `%c'
          This format element is substituted by the codeset part
          CODESET of the name of the currently selected locale.  See
          the explanation of the format above.

    `%%'
          Since `%' is used in a meta character there must be a way to
          express the `%' character in the result itself.  Using `%%'
          does this just like it works for `printf'.

     Using `NLSPATH' allows arbitrary directories to be searched for
     message catalogs while still allowing different languages to be
     used.  If the `NLSPATH' environment variable is not set, the
     default value is

          PREFIX/share/locale/%L/%N:PREFIX/share/locale/%L/LC_MESSAGES/%N

     where PREFIX is given to `configure' while installing the GNU C
     Library (this value is in many cases `/usr' or the empty string).

     The remaining problem is to decide which must be used.  The value
     decides about the substitution of the format elements mentioned
     above.  First of all the user can specify a path in the message
     catalog name (i.e., the name contains a slash character).  In this
     situation the `NLSPATH' environment variable is not used.  The
     catalog must exist as specified in the program, perhaps relative
     to the current working directory.  This situation in not desirable
     and catalogs names never should be written this way.  Beside this,
     this behavior is not portable to all other platforms providing the
     `catgets' interface.

     Otherwise the values of environment variables from the standard
     environment are examined (Note: Standard Environment).  Which
     variables are examined is decided by the FLAG parameter of
     `catopen'.  If the value is `NL_CAT_LOCALE' (which is defined in
     `nl_types.h') then the `catopen' function use the name of the
     locale currently selected for the `LC_MESSAGES' category.

     If FLAG is zero the `LANG' environment variable is examined.  This
     is a left-over from the early days where the concept of the locales
     had not even reached the level of POSIX locales.

     The environment variable and the locale name should have a value
     of the form `LANG[_TERR[.CODESET]]' as explained above.  If no
     environment variable is set the `"C"' locale is used which
     prevents any translation.

     The return value of the function is in any case a valid string.
     Either it is a translation from a message catalog or it is the
     same as the STRING parameter.  So a piece of code to decide
     whether a translation actually happened must look like this:

          {
            char *trans = catgets (desc, set, msg, input_string);
            if (trans == input_string)
              {
                /* Something went wrong.  */
              }
          }

     When an error occurred the global variable ERRNO is set to

    EBADF
          The catalog does not exist.

    ENOMSG
          The set/message tuple does not name an existing element in the
          message catalog.

     While it sometimes can be useful to test for errors programs
     normally will avoid any test.  If the translation is not available
     it is no big problem if the original, untranslated message is
     printed.  Either the user understands this as well or s/he will
     look for the reason why the messages are not translated.

   Please note that the currently selected locale does not depend on a
call to the `setlocale' function.  It is not necessary that the locale
data files for this locale exist and calling `setlocale' succeeds.  The
`catopen' function directly reads the values of the environment
variables.

 - Function: char * catgets (nl_catd CATALOG_DESC, int SET, int
          MESSAGE, const char *STRING)
     The function `catgets' has to be used to access the massage catalog
     previously opened using the `catopen' function.  The CATALOG_DESC
     parameter must be a value previously returned by `catopen'.

     The next two parameters, SET and MESSAGE, reflect the internal
     organization of the message catalog files.  This will be explained
     in detail below.  For now it is interesting to know that a catalog
     can consists of several set and the messages in each thread are
     individually numbered using numbers.  Neither the set number nor
     the message number must be consecutive.  They can be arbitrarily
     chosen.  But each message (unless equal to another one) must have
     its own unique pair of set and message number.

     Since it is not guaranteed that the message catalog for the
     language selected by the user exists the last parameter STRING
     helps to handle this case gracefully.  If no matching string can
     be found STRING is returned.  This means for the programmer that

        * the STRING parameters should contain reasonable text (this
          also helps to understand the program seems otherwise there
          would be no hint on the string which is expected to be
          returned.

        * all STRING arguments should be written in the same language.

   It is somewhat uncomfortable to write a program using the `catgets'
functions if no supporting functionality is available.  Since each
set/message number tuple must be unique the programmer must keep lists
of the messages at the same time the code is written.  And the work
between several people working on the same project must be coordinated.
We will see some how these problems can be relaxed a bit (Note: Common
Usage).

 - Function: int catclose (nl_catd CATALOG_DESC)
     The `catclose' function can be used to free the resources
     associated with a message catalog which previously was opened by a
     call to `catopen'.  If the resources can be successfully freed the
     function returns `0'.  Otherwise it return `-1' and the global
     variable ERRNO is set.  Errors can occur if the catalog descriptor
     CATALOG_DESC is not valid in which case ERRNO is set to `EBADF'.


automatically generated by info2www version 1.2.2.9