The functions to retrieve the translations for a given message have a remarkable simple interface. But to provide the user of the program still the opportunity to select exactly the translation s/he wants and also to provide the programmer the possibility to influence the way to locate the search for catalogs files there is a quite complicated underlying mechanism which controls all this. The code is complicated the use is easy.
Basically we have two different tasks to perform which can also be
performed by the
There can be arbitrarily many packages installed and they can follow different guidelines for the placement of their files.
This is the functionality required by the specifications for
gettext and this is also what the
catgets functions are
able to do. But there are some problems unresolved:
deutschand the program should always react the same.
de_DE.ISO-8859-1which means German, spoken in Germany, coded using the ISO 8859-1 character set there is the possibility that a message catalog matching this exactly is not available. But there could be a catalog matching
deand if the character set used on the machine is always ISO 8859-1 there is no reason why this later message catalog should not be used. (We call this message inheritance.)
We can divide the configuration actions in two parts: the one is performed by the programmer, the other by the user. We will start with the functions the programmer can use since the user configuration will be based on this.
As the functions described in the last sections already mention separate
sets of messages can be selected by a domain name. This is a
simple string which should be unique for each program part that uses a
separate domain. It is possible to use in one program arbitrarily many
domains at the same time. E.g., the GNU C Library itself uses a domain
libc while the program using the C Library could use a
foo. The important point is that at any time
exactly one domain is active. This is controlled with the following
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem | See POSIX Safety Concepts.
textdomain function sets the default domain, which is used in
gettext calls, to domainname. Please note that
dcgettext calls are not influenced if the
domainname parameter of these functions is not the null pointer.
Before the first call to
textdomain the default domain is
messages. This is the name specified in the specification of
gettext API. This name is as good as any other name. No
program should ever really use a domain with this name since this can
only lead to problems.
The function returns the value which is from now on taken as the default
domain. If the system went out of memory the returned value is
NULL and the global variable errno is set to
Despite the return value type being
char * the return string must
not be changed. It is allocated internally by the
If the domainname parameter is the null pointer no new default domain is set. Instead the currently selected default domain is returned.
If the domainname parameter is the empty string the default domain
is reset to its initial value, the domain with the name
This possibility is questionable to use since the domain
really never should be used.
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.
bindtextdomain function can be used to specify the directory
which contains the message catalogs for domain domainname for the
different languages. To be correct, this is the directory where the
hierarchy of directories is expected. Details are explained below.
For the programmer it is important to note that the translations which
come with the program have to be placed in a directory hierarchy starting
at, say, /foo/bar. Then the program should make a
bindtextdomain call to bind the domain for the current program to
this directory. So it is made sure the catalogs are found. A correctly
running program does not depend on the user setting an environment
bindtextdomain function can be used several times and if the
domainname argument is different the previously bound domains
will not be overwritten.
If the program which wish to use
bindtextdomain at some point of
time use the
chdir function to change the current working
directory it is important that the dirname strings ought to be an
absolute pathname. Otherwise the addressed directory might vary with
If the dirname parameter is the null pointer
returns the currently selected directory for the domain with the name
bindtextdomain function returns a pointer to a string
containing the name of the selected directory name. The string is
allocated internally in the function and must not be changed by the
user. If the system went out of core during the execution of
bindtextdomain the return value is
NULL and the global
variable errno is set accordingly.