gettext(3scl)gettext(3scl)NAME
gettext, dgettext, dcgettext, textdomain, bindtextdomain - retrieve
translated messages
SYNOPSIS
#include <libintl.h> #include <locale.h> /* for dcgettext only */
char *gettext(const char *msgid);
char *dgettext(const char *domainname,
const char *msgid);
char *dcgettext(const char *domainname,
const char *msgid,
int category);
char *textdomain(const char *domainname);
char *bindtextdomain(const char *domainname,
const char *dirname);
PARAMETERS
A null-terminated string that specifies the message for which transla‐
tion is requested. A null-terminated string that specifies the domain
from which translation is attempted. Specifies the locale category
used by dcgettext A null-terminated string that specifies the domain
from which translation is attempted A null-terminated string that spec‐
ifies the directory beneath which the message object resides.
DESCRIPTION
The gettext() function retrieves a translated string that corresponds
to the specified msgid string from a message object file. The transla‐
tion occurs within the context of a domain and locale, which for this
function are specified by calling textdomain() prior to gettext()
and the using the value of the LC_MESSAGES category of the current
locale. If a successful call to textdomain() has not been made prior to
calling gettext() the default domain - messages - is used.
The dgettext() function performs the same task as gettext(), except
that the domain from which the message is retrieved is explicitly spec‐
ified with the domainname argument. The domain context for subsequent
calls is not affected - the specified domain is only valid for the
duration of the dgettext() call. As with gettext(), the locale used is
specified by the value of LC_MESSAGES category.
The dcgettext() function performs the same task as the previous func‐
tions, except that an alternative locale category can be specified with
the category argument. This must be one of the valid LC_XXX values
defined in locale.h.
For all of the above functions, if msgid or domainname are NULL the
results are undefined. Similarly the result is undefined if category is
not a recognised value.
The textdomain() function changes the domain that is used for message
translation with function gettext(). Passing a domainname string will
set the domain for all subsequent gettext() calls. Passing an empty
string will reset the domain to the default name - messages. Passing a
NULL parameter will return the name of the current domain.
The bindtextdomain() function specifies an alternative location for a
message object file. Passing a domainname string will set the domain
for all subsequent gettext() calls. If dirname is NULL, it returns the
binding associated with the specified domain. If domainname is NULL, a
null pointer is returned.
The bindtextdomain() function can be used to avoid clashes of domain
name use. For example, if two applications each use the "errors" domain
but supply different "errors.mo" message object files, the appropriate
one can be located by calling bindtextdomain() from the respective
applications.
IMPLEMENTATION NOTES
By default, the functions search for the message object file, named
domainname.mo, in the directory /usr/local/share/locale/lang/LC_MES‐
SAGES where lang is the locale name specified with the LC_MESSAGES
environment variable, or implied by changing the current locale with
setlocale() or by defining LANG. The bindtextdomain() function can be
used to specify an alternative location, replacing the pathname compo‐
nent up to lang.
These functions are implemented by the GNU gettext package. This is not
supplied with SCL but can be downloaded from GNU distribution sites or
obtained from the Freeware Source CD that is supplied with Tru64 UNIX.
Additional documentation about this command can be obtained by using
the info command once GNU gettext has been installed.
RETURN VALUES
The gettext(), dgettext() and dcgettext() functions return a pointer to
the translated string if the call is successful, otherwise the original
msgid parameter is returned. The buffer pointed to by the return value
should not be used to modify the returned string and this buffer is
deemed invalid after a subsequent call to another function.
The textdomain() function returns a pointer to the current domain name.
If the domain name is invalid no error indication is given, but the
effect will be that no message translation occurs with the gettext
functions.
The bindtextdomain() function returns a pointer to the name of the
directory where the message objects reside (that is the current bind‐
ing) or NULL if the domainname parameter is NULL.
RELATED INFORMATION
Function: setlocale(3)
Commands: gettext(1scl), locale(1)
Manual: Solaris Compatibility Library User's Guide
gettext(3scl)