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(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 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.

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 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.mo

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_MESSAGES