svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
gettext(3c)
gettext(3C) Standard C Library Functions gettext(3C)
NAME
gettext, dgettext, dcgettext, ngettext, dngettext, dcngettext, textdo‐
main, bindtextdomain, bind_textdomain_codeset - message handling func‐
tions
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 re‐
trieve 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 undeter‐
mined until the function is called. The msgid argument is a null-termi‐
nated 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() func‐
tions search for the message string using the msgid1 argument as the
key and the n argument to determine the plural form. If no message cat‐
alogues are found, msgid1 is returned if n == 1, otherwise msgid2 is
returned.
The NLSPATH environment variable (see environ(7)) is searched in its
entirety first for the location of the LC_MESSAGES catalogue. The set‐
ting of the LC_MESSAGES category of the current locale determines the
locale used by gettext() and dgettext() for string retrieval. The cate‐
gory argument determines the locale used by dcgettext(). If NLSPATH
contains %L and the current value of it is a canonical locale name to
an obsoleted Solaris locale name as described in locale_alias(7) and
there is no message catalog for the canonical locale name, for a better
backward compatibility, the routines use the obsoleted Solaris locale
names in place for %L as aliases for the canonical locale name and try
to locate the desired message catalogue. If that does not yield a mes‐
sage catalogue and the value of %L is an accepted and supported locale
name alias as described in locale_alias(7), the matching canonical lo‐
cale name is used in place for %L to locate the desired message cata‐
logue. If that still does not yield a message catalogue, some varia‐
tions of the current locale name are formulated internally by using its
language and territory elements, such as <language>_<territory> and
<language> and tried one by one in place for %L to locate the desired
message catalogue. In this case, the message catalogue must be a GNU-
compatible message catalogue and, if not, such message catalogue are
ignored. If NLSPATH is not defined and the current locale is "C", get‐
text(), 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 speci‐
fied by NLSPATH, the routines search for the message catalogue using
the scheme described in the following paragraph.
The LANGUAGE environment variable is examined in its entirety to deter‐
mine 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, in the specified order, each locale name and
also its variations that are internally formulated by using language
and territory elements are tried one by one and if a GNU-compatible
message catalogue is found, it is used to return target strings. If no
GNU-compatible message catalogue is found for all locales specified in
the LANGUAGE and if there are accepted and supported locale name
aliases for any of the locale names in the LANGUAGE, as specified in
locale_alias(7) and in the same manner as described in the NLSPATH de‐
scription at the above for %L and the current locale name, the locale
name aliases are used once again to search corresponding GNU-compatible
message catalogues. If a GNU-compatible message catalogue is found but
failed to find a corresponding msgid, the msgid string is returned. 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/lo‐
cale/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().
In this last stage of search of message catalogue, if there is still no
message catalogue found with the locale name, its matching obsoleted
Solaris locale names or canonical locale name (if any as described in
locale_alias(7)) and also variations that are formulated internally by
using language and territory elements are used in place of the locale
name to locate the message catalogue in the same manner as described in
the above for the processing of the locale names defined in the LAN‐
GUAGE.
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 dcnget‐
text() function call.
The textdomain() function sets or queries the name of the current do‐
main of the active LC_MESSAGES locale category. The domainname argument
is a null-terminated string that can contain only the characters al‐
lowed 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, name‐
space collisions can be avoided by using bindtextdomain(). If textdo‐
main() is not called, a default domain is selected. The setting of do‐
main 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 ar‐
gument can be an absolute or relative pathname being resolved when get‐
text(), 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 out‐
put 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 se‐
lected codeset for the domain with the name domainname. It returns a
null pointer if a codeset has not yet been selected. The bind_textdo‐
main_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() func‐
tion 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 mes‐
sage string if the search succeeds. If the search fails, msgid1 is re‐
turned 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 con‐
taining 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 domain‐
name 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 con‐
taining 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 do‐
mainname is limited to TEXTDOMAINMAX (256) bytes.
The gettext(), dgettext(), dcgettext(), ngettext(), dngettext(), dc‐
ngettext(), 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 bindtextdo‐
main() functions work with both Solaris message catalogues and GNU-com‐
patible 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_MES‐
SAGES
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, lan‐
guage 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_MES‐
SAGES
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilitySee below. _ MT-LevelSafe with ex‐
ceptions
The external variables _nl_msg_cat_cntr and _nl_domain_bindings are Un‐
committed. Otherwise, the interface is Committed.
SEE ALSO
msgfmt(1), xgettext(1), iconv_open(3C), setlocale(3C), lib‐
intl.h(3HEAD), attributes(7), environ(7), locale_alias(7)
gettext APIs in Internationalizing and Localizing Applications in Ora‐
cle Solaris
HISTORY
The ngettext(), dngettext(), bind_textdomain_codeset(), and dcnget‐
text() functions, and GNU compatibility in the existing functions, were
added to Solaris in the Solaris 9 release.
The dcgettext() function was added to Solaris in the Solaris 2.4 re‐
lease.
The dgettext() and bindtextdomain() functions were added to Solaris in
the Solaris 2.0 release.
The gettext() and textdomain() functions have been included in all Sun
and Oracle releases of Solaris.
Oracle Solaris 11.4 25 Nov 2024 gettext(3C)