GETTEXT(3) — C LIBRARY FUNCTIONS

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 implementation-defined default locale (this default locale could contain any language). 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 gettext() will return msgtag.

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

• Non-existent archive selected after setlocale() or textdomain() was called.

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

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

• domainname contains an invalid character.

• domainname is longer than LINE_MAX bytes in length.

• 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’.

Museum