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 nul-terminated string.
The
ngettext(),
dngettext(), and
dcngettext() functions are equivalent to
gettext(),
dgettext(), and
dcgettext(), respectively, except for the handling of plural forms. The
ngettext(),
dngettext(), and
dcngettext() functions search for the message string using the
msgid1 argument as the key, using the argument
n to determine the plural form. If no message catalogs are found,
msgid1 is returned if
n == 1, otherwise
msgid2 is returned.
The
LANGUAGE environment variable is examined first to determine the message catalogs to be used. The value of the
LANGUAGE environment variable is a list of locale names separated by colon (:) character. If the
LANGUAGE environment variable is defined, each locale name is tried in the specified order and if a message catalog containing the requested message is found, the message is returned. If the
LANGUAGE environment variable is defined but failed to locate a message catalog, the
msgid string will be returned.
If the
LANGUAGE environment variable is not defined,
LC_ALL,
LC_xxx, and
LANG environment variables are examined to locate the message catalog, following the convention used by the
setlocale(3) function.
The pathname used to locate the message catalog is
dirname/locale/category/domainname.mo, where dirname is the directory specified by
bindtextdomain(), locale is a locale name determined by the definition of environment variables,
category is
LC_MESSAGES if
gettext(),
ngettext(),
dgettext(), or
dngettext() is called, otherwise
LC_xxx where the name is the same as the locale category name specified by the
category argument of
dcgettext() or
dcngettext().
domainname is the name of the domain specified by
textdomain() or the
domainname argument of
dgettext(),
dngettext(),
dcgettext(), or
dcngettext().
For
gettext() and
ngettext(), 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(),
dngettext(),
dcgettext(), and
dcngettext(), 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(),
dngettext(),
dcgettext(), or
dcngettext() function call.
The
dcgettext() and
dcngettext() functions require additional argument
category for retrieving message string for other than
LC_MESSAGES category. Available value for the
category argument are
LC_CTYPE,
LC_COLLATE,
LC_MESSAGES,
LC_MONETARY,
LC_NUMERIC, and
LC_TIME. The call of
dcgettext(
domainname,
msgid,
LC_MESSAGES) is equivalent to
dgettext(
domainname,
msgid). Note that
LC_ALL must not be used.
The
textdomain() function sets or queries the name of the current domain of the active
LC_MESSAGES locale category. The
domainname argument is a nul-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(3), 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 pathname being resolved when
gettext(),
ngettext(),
dgettext(),
dngettext(),
dcgettext(), or
dcngettext() are called. If
domainname is a
NULL pointer or an empty string,
bindtextdomain() returns a
NULL pointer. If
bindtextdomain() is not called, implementation-defined default directory is used.
The
bind_textdomain_codeset() function can be used to specify the output
codeset for message catalogs for domain
domainname. The
codeset argument must be a valid codeset name which can be used for the
iconv_open(3) function.
If the
codeset argument is the
NULL pointer,
bind_textdomain_codeset() returns the currently selected
codeset for the domain with the name
domainname. It returns a
NULL pointer if no
codeset has yet been selected.
The
bind_textdomain_codeset() function can be used several times. If used multiple times, with the same
domainname argument, the later call overrides the settings made by the earlier one.
The
bind_textdomain_codeset() function returns a pointer to a string containing the name of the selected
codeset.