GETTEXT(3C) Standard C Library Functions GETTEXT(3C)
NAME
gettext, dgettext, dcgettext, ngettext, dngettext, dcngettext,
textdomain, bindtextdomain, bind_textdomain_codeset - message handling
functions
SYNOPSIS
Solaris and GNU-compatible #include <libintl.h>
char *gettext(
const char *msgid);
char *dgettext(
const char *domainname,
const char *msgid);
char *textdomain(
const char *domainname);
char *bindtextdomain(
const char *domainname,
const char *dirname);
#include <libintl.h>
#include <locale.h>
char *dcgettext(
const char *domainname,
const char *msgid,
int category);
GNU-compatible #include <libintl.h>
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 *bind_textdomain_codeset(
const char *domainname,
const char *codeset);
extern int _nl_msg_cat_cntr;
extern int *_nl_domain_bindings;
#include <libintl.h>
#include <locale.h>
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 null-terminated string.
The
ngettext(),
dngettext(), and
dcngettext() functions are equivalent to
gettext(),
dgettext(), and
dcgettext(), respectively, except for the
handling of plural forms. These functions work only with GNU-compatible
message catalogues. The
ngettext(),
dngettext(), and
dcngettext() functions search for the message string using the
msgid1 argument as the
key and the
n argument to determine the plural form. If no message
catalogues are found,
msgid1 is returned if
n == 1, otherwise
msgid2 is
returned.
The
NLSPATH environment variable (see
environ(7)) 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 using the scheme described in the following paragraph.
The
LANGUAGE environment variable is examined to determine the GNU-
compatible message catalogues to be used. The value of
LANGUAGE is a list
of locale names separated by a colon (':') character. If
LANGUAGE is
defined, each locale name is tried in the specified order and if a GNU-
compatible message catalogue is found, the message is returned. If a
GNU-compatible message catalogue is found but failed to find a
corresponding
msgid, the
msgid string is return. If
LANGUAGE is not
defined or if a Solaris message catalogue is found or no GNU-compatible
message catalogue is found in processing
LANGUAGE, the pathname used to
locate the message catalogue is
dirname/
locale/
category/
domainname.mo,
where
dirname is the directory specified by
bindtextdomain(),
locale is a
locale name, and
category is either
LC_MESSAGES if
gettext(),
dgettext(),
ngettext(), or
dngettext() is called, or
LC_XXX where the name is the
same as the locale category name specified by the
category argument to
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(),
dcgettext(),
dngettext(), 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(),
dcgettext(),
dngettext(), or
dcngettext() 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.
The
bind_textdomain_codeset() function can be used to specify the output
codeset for message catalogues for domain
domainname. The
codeset argument must be a valid codeset name that can be used for the
iconv_open(3C) function, or a null pointer. 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 a codeset has not yet been selected. The
bind_textdomain_codeset() function can be used multiple 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. The string is allocated
internally in the function and must not be changed by the user.
The external variables
_nl_msg_cat_cntr and
_nl_domain_bindings are
provided for the compatibility with the GNU
gettext() implementation.
RETURN VALUES
The
gettext(),
dgettext(), and
dcgettext() functions return the message
string if the search succeeds. Otherwise they return the
msgid string.
The
ngettext(),
dngettext(), and
dcngettext() functions return the
message string if the search succeeds. If the search fails,
msgid1 is
returned if
n == 1. Otherwise
msgid2 is returned.
The individual bytes of the string returned by
gettext(),
dgettext(),
dcgettext(),
ngettext(),
dngettext(), or
dcngettext() 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
bind_textdomain_codeset() or
setlocale(3C). If the
domainname argument to
dgettext(),
dcgettext(),
dngettext(), or
dcngettext() is a null pointer, the domain currently
bound by
textdomain() is used.
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. If
textdomain() fails, a null pointer
is returned.
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. If
bindtextdomain() fails, a
null pointer is returned.
USAGE
These functions impose no limit on message length. However, a text
domainname is limited to
TEXTDOMAINMAX (256) bytes.
The
gettext(),
dgettext(),
dcgettext(),
ngettext(),
dngettext(),
dcngettext(),
textdomain(), and
bindtextdomain() functions can be used
safely in multithreaded applications, as long as
setlocale(3C) is not
being called to change the locale.
The
gettext(),
dgettext(),
dcgettext(),
textdomain(), and
bindtextdomain() functions work with both Solaris message catalogues and
GNU-compatible message catalogues. The
ngettext(),
dngettext(),
dcngettext(), and
bind_textdomain_codeset() functions work only with GNU-
compatible message catalogues. See
msgfmt(1) for information about
Solaris message catalogues and GNU-compatible message catalogues.
FILES
/usr/lib/locale default path predicate for message domain files
/usr/lib/locale/locale/LC_MESSAGES/domainname.m o system default location for file containing messages for language
locale and
domainname /usr/lib/locale/locale/LC_XXX/domainname.mo system default location for file containing messages for language
locale and
domainname for
dcgettext() calls where
LC_XXX is
LC_CTYPE,
LC_NUMERIC,
LC_TIME,
LC_COLLATE,
LC_MONETARY, or
LC_MESSAGES dirname/locale/LC_MESSAGES/domainname .mo location for file containing messages for domain
domainname and path
predicate
dirname after a successful call to
bindtextdomain() dirname/locale/LC_XXX/domainname.mo location for files containing messages for domain
domainname, language
locale, and path predicate
dirname after a successful call
to
bindtextdomain() for
dcgettext() calls where
LC_XXX is one of
LC_CTYPE,
LC_NUMERIC,
LC_TIME,
LC_COLLATE,
LC_MONETARY, or
LC_MESSAGESATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+----------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+----------------------+
|Interface Stability | See below. |
+--------------------+----------------------+
|MT-Level | Safe with exceptions |
+--------------------+----------------------+
The external variables
_nl_msg_cat_cntr and
_nl_domain_bindings are
Uncommitted.
SEE ALSO
msgfmt(1),
xgettext(1),
iconv_open(3C),
setlocale(3C),
libintl.h(3HEAD),
attributes(7),
environ(7) April 9, 2016
GETTEXT(3C)