DESCRIPTION

The gettext()
, dgettext()
, and dcgettext()
functions attempt to retrieve a target string based on the specified msgid
argument within the context of a specific domain and the current locale. The length of strings returned by gettext()
, dgettext()
, and dcgettext()
is undetermined until the function is called. The msgid
argument is a null-terminated string.

The NLSPATH
environment variable (see environ(5)
)
is searched first for the location of the LC_MESSAGES
catalogue. The setting of the LC_MESSAGES
category of the current locale determines the locale used by gettext()
and dgettext()
for string retrieval. The category
argument determines the locale used by dcgettext().
If NLSPATH
is not defined and the current locale is "C", gettext()
, dgettext()
, and dcgettext()
simply return the message string that was passed.
In a locale other than "C", if NLSPATH
is not defined or if a message catalogue is not found in any of the components specified by NLSPATH
, the routines search for the message
catalogue dirname
/locale
/category
/domainname
.mo
, after querying bindtextdomain()
for dirname
.

For gettext()
, the domain used is set by the last valid call to textdomain()
. If a valid call to textdomain()
has not been made, the default
domain (called messages
) is used.

For dgettext()
and dcgettext()
, the domain used is specified by the domainname
argument. The domainname
argument
is equivalent in syntax and meaning to the domainname
argument to textdomain()
, except that the selection of the domain is valid only for the duration of the dgettext()
or dcgettext()
function call.

The textdomain()
function sets or queries the name of the current domain of the active LC_MESSAGES
locale category. The domainname
argument
is a null-terminated string that can contain only the characters allowed in legal filenames.

The domainname
argument is the unique name of a domain on the system. If there are multiple versions of the same domain on one system, namespace collisions can be avoided by
using bindtextdomain()
. If textdomain()
is not called, a default domain is selected. The setting of domain made by the last valid call to textdomain()
remains valid across subsequent calls to setlocale(3C)
, and gettext()
.

The domainname
argument is applied to the currently active LC_MESSAGES
locale.

The current setting of the domain can be queried without affecting the current state of the domain by calling textdomain()
with domainname
set to the null
pointer. Calling textdomain()
with a domainname
argument of a null string sets the domain to the default domain (messages
).

The bindtextdomain()
function binds the path predicate for a message domain domainname
to the value contained in dirname
. If domainname
is a non-empty string and has not been bound previously, bindtextdomain()
binds domainname
with dirname
.

If domainname
is a non-empty string and has been bound previously, bindtextdomain()
replaces the old binding with dirname
. The dirname
argument can be an absolute or relative pathname being resolved when gettext()
, dgettext()
, or dcgettext()
are called. If domainname
is a null pointer or an empty string, bindtextdomain()
returns NULL.
User defined domain names cannot begin with the string SYS_
. Domain names beginning with this string are reserved for system use.

RETURN VALUES

The individual bytes of the string returned by gettext()
, dgettext()
, or dcgettext()
can contain any value other than null. If msgid
is a null pointer, the return value is undefined. The string returned must not be modified by the program, and can be invalidated by a subsequent call to gettext()
, dgettext()
, dcgettext(),
or setlocale(3C)
.
If the domainname
argument to dgettext()
or dcgettext()
is a null pointer, the results are undefined.

If the target string cannot be found in the current locale and selected domain, gettext()
, dgettext()
, and dcgettext()
return msgid
.

The normal return value from textdomain()
is a pointer to a string containing the current setting of the domain. If domainname
is a null pointer, textdomain()
returns a pointer to the string containing the current domain. If textdomain()
was not previously called and domainname
is a null string,
the name of the default domain is returned. The name of the default domain is messages.

The return value from bindtextdomain()
is a null-terminated string containing dirname
or the directory binding associated with domainname
if dirname
is NULL.
If no binding is found, the default return value is /usr/lib/locale
. If domainname
is a null pointer or an empty string, bindtextdomain()
takes no action and returns a null pointer. The string returned must not be modified by the caller.

USAGE

These routines impose no limit on message length. However, a text domainname
is limited to TEXTDOMAINMAX
(256) bytes.

The gettext()
, dgettext()
, dcgettext()
, textdomain()
, and bindtextdomain()
can be used safely in multithreaded
applications, as long as setlocale(3C)
is not being called to change the locale.

FILES

/usr/lib/locale

The default path predicate for message domain files.

/usr/lib/locale/locale
/LC_MESSAGES/domainname
.mo

system default location for file containing
messages for language locale
and domainname