NAME
gettext,
dgettext,
ngettext,
dngettext,
textdomain,
bindtextdomain,
bind_textdomain_codeset,
dcgettext,
dcngettext —
message handling
functions
LIBRARY
Internationalized Message Handling Library (libintl,
-lintl)
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
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.
SEE ALSO
setlocale(3),
nls(7)
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).