GETTEXT(3) Library Functions Manual GETTEXT(3)
gettext, textdomain - retrieve a message string, get and set text
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
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().
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
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'.
22 January 1990 GETTEXT(3)