November 10, 2004 GETTEXT 3

### NAME

gettext, dgettext, ngettext, dngettext, textdomain, bindtextdomain, bind_textdomain_codeset, dcgettext, dcngettext - message handling functions

### LIBRARY

Internationalized Message Handling Library (libintl, -lintl)

### SYNOPSIS

```char``*` gettext(```const char *msgid`)
```char``*` dgettext(```const char *domainname``, const char *msgid`)
```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``*` textdomain(```const char *domainname`)
```char``*` bindtextdomain(```const char *domainname``, const char *dirname`)
```char``*` bind_textdomain_codeset(```const char *domainname``, const char *codeset`)
```char``*` dcgettext(```const char *domainname``, const char *msgid``, int category`)
```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 nul-terminated string.

The ngettext(``), dngettext(``), and dcngettext(``) functions are equivalent to gettext(``), dgettext(``), and dcgettext(``), respectively, except for the handling of plural forms. The ngettext(``), dngettext(``), and dcngettext(``) functions search for the message string using the ```msgid1` argument as the key, using the argument ```n` to determine the plural form. If no message catalogs are found, ```msgid1` is returned if ```n````==``1`, otherwise ```msgid2` is returned.

The ```LANGUAGE` environment variable is examined first to determine the message catalogs to be used. The value of the ```LANGUAGE` environment variable is a list of locale names separated by colon (:) character. If the ```LANGUAGE` environment variable is defined, each locale name is tried in the specified order and if a message catalog containing the requested message is found, the message is returned. If the ```LANGUAGE` environment variable is defined but failed to locate a message catalog, the ```msgid` string will be returned.

If the ```LANGUAGE` environment variable is not defined, ```LC_ALL`, ```LC_xxx`, and ```LANG` environment variables are examined to locate the message catalog, following the convention used by the setlocale(3) function.

The pathname used to locate the message catalog is ```dirname/locale/category/domainname.mo`, where dirname is the directory specified by bindtextdomain(``), locale is a locale name determined by the definition of environment variables, ```category` is ```LC_MESSAGES` if gettext(``), ngettext(``), dgettext(``), or dngettext(``) is called, otherwise ```LC_xxx` where the name is the same as the locale category name specified by the ```category` argument of dcgettext(``) or dcngettext(``). ```domainname` is the name of the domain specified by textdomain(``) or the ```domainname` argument of dgettext(``), dngettext(``), 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(``), dngettext(``), dcgettext(``), 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(``), dngettext(``), dcgettext(``), or dcngettext(``) function call.

The dcgettext(``) and dcngettext(``) functions require additional argument ```category` for retrieving message string for other than ```LC_MESSAGES` category. Available value for the ```category` argument are ```LC_CTYPE`, ```LC_COLLATE`, ```LC_MESSAGES`, ```LC_MONETARY`, ```LC_NUMERIC`, and ```LC_TIME`. The call of dcgettext(```domainname``, msgid``, LC_MESSAGES`) is equivalent to dgettext(```domainname``, msgid`). Note that ```LC_ALL` must not be used.

The textdomain(``) function sets or queries the name of the current domain of the active ```LC_MESSAGES` locale category. The ```domainname` argument is a nul-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(3), 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 pathname being resolved when gettext(``), ngettext(``), dgettext(``), dngettext(``), dcgettext(``), or dcngettext(``) are called. If ```domainname` is a ```NULL` pointer or an empty string, bindtextdomain(``) returns a ```NULL` pointer. If bindtextdomain(``) is not called, implementation-defined default directory is used.

The bind_textdomain_codeset(``) function can be used to specify the output ```codeset` for message catalogs for domain ```domainname`. The ```codeset` argument must be a valid codeset name which can be used for the iconv_open(3) function.

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 no ```codeset` has yet been selected.

The bind_textdomain_codeset(``) function can be used several 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`.

### SEE ALSO

setlocale(3), nls(7)

### HISTORY

The functions are implemented by Citrus project, based on the documentations for GNU gettext.

### BUGS

bind_textdomain_codeset(``) does not work at this moment (it always fails).