NAME
gettext
, dgettext
,
ngettext
, dngettext
,
textdomain
, bindtextdomain
,
bind_textdomain_codeset
,
dcgettext
, dcngettext
— message handling
functions
LIBRARY
library “libintl”
SYNOPSIS
#include
<libintl.h>
char *
gettext
(const
char *msgid);
char *
dgettext
(const
char *domainname, const
char *msgid);
char *
ngettext
(const
char *msgid1, const char
*msgid2, unsigned long
int n);
char *
dngettext
(const
char *domainname, const
char *msgid1, const char
*msgid2, unsigned long
int n);
char *
textdomain
(const
char *domainname);
char *
bindtextdomain
(const
char *domainname, const
char *dirname);
char *
bind_textdomain_codeset
(const
char *domainname, const
char *codeset);
#include
<libintl.h>
#include <locale.h>
char *
dcgettext
(const
char *domainname, const
char *msgid, int
category);
char *
dcngettext
(const
char *domainname, const
char *msgid1, const char
*msgid2, unsigned long
int n, int
category);
DESCRIPTION
Thegettext
(),
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.
SEE ALSO
HISTORY
The functions are implemented by Citrus project, based on the documentations for GNU gettext.
BUGS
bind_textdomain_codeset
() does not work at
this moment (it always fails).