Tribblix: manual page: gettext.3c

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_MESSAGES

ATTRIBUTES

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.