unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

GETTEXT(3)                 Library Functions Manual                 GETTEXT(3)



NAME
       gettext,  textdomain  -  retrieve  a  message  string, get and set text
       domain

SYNOPSIS
       char *gettext(msgtag)
       char *msgtag;

       char *textdomain(domainname)
       char *domainname;

DESCRIPTION
       gettext()  returns  a  pointer  to  a  null-terminated  string  (target
       string).   msgtag  is  a  string  used at run-time to select the target
       string from the current domain of the active  pool  of  messages.   The
       length  and  contents of strings returned by gettext() are undetermined
       until called at run-time.  The string returned by gettext()  cannot  be
       modified  by the caller, but may be overwritten by a subsequent call to
       gettext().  The LC_MESSAGES  locale  category  setting  determines  the
       locale of strings that gettext() returns.

       The  calling  process  can  dynamically change the choice of locale for
       strings returned by gettext() by invoking  the  setlocale(3V)  function
       with  the  correct category and the required locale.  If setlocale() is
       not called or is called with an invalid value,  gettext()  defaults  to
       the  "C"  locale.  The default name for the current domain is the empty
       string.

       gettext() first attempts to resolve the target string from  the  active
       domain  and  locale of the message pool.  The current locale and domain
       are determined by the combination of both the LC_MESSAGES  category  of
       locale and the current domain setting.

       If  the  target  string cannot be found by using the current locale and
       domain then msgtag and current domain are applied  to  the  implementa-
       tion-defined default locale (this default locale could contain any lan-
       guage).  If the default locale does not also contain the target  string
       then the msgtag and current domain will be applied to the "C" locale of
       the message pool.  If the target string still cannot be found then get-
       text() will return msgtag.

       Any  of  the  following  conditions  will result in a message not being
       found in the string archive:

              o  Non-existent archive selected after  setlocale()  or  textdo-
                 main() was called.

              o  Non-existent  archive  in  the "C" environment if setlocale()
                 was not called.

              o  Non-existent or deleted entry in the archive.

       textdomain() sets the current domain to domainname.   Subsequent  calls
       to gettext() refer to this domain.  If domainname is NULL, textdomain()
       returns the name of the current domain without changing it.

       The setting of domain made by the  last  successful  textdomain()  call
       remains valid across any number of subsequent calls to setlocale().

RETURN VALUES
       gettext()  returns  a  pointer  to the null-terminated target string on
       success.  On failure, gettext() returns msgtag.

       textdomain() returns a pointer to the name of the current  domain.   If
       the  domain has not been set prior to this call, textdomain() returns a
       pointer to an empty string.  textdomain() returns NULL if:

              o  domainname contains an invalid character.

              o  domainname is longer than LINE_MAX bytes in length.

              o  If, at the time of the call to textdomain(), the  combination
                 of  current  locale and domainname creates a domain that does
                 not exist at run-time.  Note: in this case  textdomain()  may
                 have  been  called  prior to a successful setlocale(3V) call,
                 but textdomain() will always  check  against  current  locale
                 setting.

EXAMPLES
       The following produces `Hit Return\n' in a locale that is invalid or is
       valid and contains the same target string as the key:

              printf( gettext( "Hit Return\n" );

       On a system whose default language is French, and whose process has the
       LC_MESSAGES category validly set, the following might print: `Bonjour':

              setlocale( LC_MESSAGES, "" );
              textdomain( "Morning" );
              printf( gettext( "Welcome" );

       If   the  LC_MESSAGES  category  was  invalidly  set  and  the  default
       (LC_DEFAULT) is set to English, the  last  example  above  might  print
       `Good  morning'.   If  the  default  is not set or is also invalid, the
       example would print `Welcome'.

SEE ALSO
       setlocale(3V), installtxt(8)




                                22 January 1990                     GETTEXT(3)