Standard C Library Functions gettext(3C)
NAME
gettext, dgettext, dcgettext, ngettext, dngettext, dcnget-
text, textdomain, bindtextdomain, bind_textdomain_codeset -
message handling functionsSYNOPSIS
Solaris and GNU-compatible
#include
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
#include
char *dcgettext(const char *domainname, const char *msgid, int category);GNU-compatible
#include
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
#include
char *dcngettext(const char *domainname, const char *msgid1, const char *msgid2, unsigned long int n, int category);SunOS 5.11 Last change: 4 Jun 2008 1
Standard C Library Functions gettext(3C)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 func-
tion 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)) issearched first for the location of the LC_MESSAGES catalo-
gue. The setting of the LC_MESSAGES category of the current
locale determines the locale used by gettext() and dget-
text() for string retrieval. The category argument deter-
mines the locale used by dcgettext(). If NLSPATH is notdefined and the current locale is "C", gettext(), dget-
text(), 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 forthe message catalogue using the scheme described in the fol-
lowing paragraph. The LANGUAGE environment variable is examined to determinethe 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 nameis tried in the specified order and if a GNU-compatible mes-
sage catalogue is found, the message is returned. If aGNU-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 isfound 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, wheredirname is the directory specified by bindtextdomain(),
locale is a locale name, and category is either LC_MESSAGES
if gettext(), dgettext(), ngettext(), or dngettext() iscalled, or LC_XXX where the name is the same as the locale
SunOS 5.11 Last change: 4 Jun 2008 2
Standard C Library Functions gettext(3C)category name specified by the category argument to dcget-
text() or dcngettext(). For gettext() and ngettext(), the domain used is set by thelast 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 tothe 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 byusing bindtextdomain(). If textdomain() is not called, a
default domain is selected. The setting of domain made bythe last valid call to textdomain() remains valid across
subsequent calls to setlocale(3C), and gettext(). The domainname argument is applied to the currently activeLC_MESSAGES locale.
The current setting of the domain can be queried without affecting the current state of the domain by callingtextdomain() with domainname set to the null pointer. Cal-
ling 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 dir-
name.SunOS 5.11 Last change: 4 Jun 2008 3
Standard C Library Functions gettext(3C)If domainname is a non-empty string and has been bound pre-
viously, 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 oran 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 codesetname 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. Thebind_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 theearlier 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 dcnget-
text() 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 tobind_textdomain_codeset() or setlocale(3C). If the domain-
name argument to dgettext(),dcgettext(), dngettext(), orSunOS 5.11 Last change: 4 Jun 2008 4
Standard C Library Functions gettext(3C) dcngettext() is a null pointer, the the domain currentlybound by textdomain() is used.
The normal return value from textdomain() is a pointer to a
string containing the current setting of the domain. Ifdomainname 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 thedefault 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 associ-
ated 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. Ifbindtextdomain() 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(), dnget-
text(), 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 nget-
text(), dngettext(), dcngettext(), andbind_textdomain_codeset() functions work only with GNU-
compatible message catalogues. See msgfmt(1) for informa-
tion 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
SunOS 5.11 Last change: 4 Jun 2008 5
Standard C Library Functions gettext(3C) 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() callswhere 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 domain-
name and path predicate dirname after a successful callto bindtextdomain()
dirname/locale/LC_XXX/domainname.mo
location for files containing messages for domain domainname, language locale, and path predicate dirnameafter a successful call to bindtextdomain() for dcget-
text() calls where LC_XXX is one of LC_CTYPE,
LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, or
LC_MESSAGES
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| 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), libintl.h(3HEAD),
setlocale(3C), attributes(5), environ(5)SunOS 5.11 Last change: 4 Jun 2008 6