NAME

gettext, dgettext, textdomain, bindtextdomain − message handling functions

SYNOPSIS

cc [ flag ... ] file ... −lintl [ library ... ]

#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);

DESCRIPTION

gettext() and dgettext() 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() and dgettext() is undetermined until the function is called.  The msgid argument is a null-terminated string. 

The setting of the LC_MESSAGES category of the current locale determines the locale used by gettext() and dgettext() for string retrieval. 

For gettext(), 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(), 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() call. 

textdomain() 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). 

bindtextdomain() 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 bounded previously, bindtextdomain() binds domainname with dirname.

If domainname is a non-empty string and has been bounded previously, bindtextdomain() replaces the old binding with dirname. dirname can be an absolute or relative pathname being resolved when gettext() or dgettext() 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. 

RETURN VALUES

The individual bytes of the string returned by gettext() or dgettext() 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 gettext(), dgettext(), or setlocale(3C).  If the domainname argument to dgettext() is a NULL pointer, the results are undefined. 

If the target string cannot be found in the current locale and selected domain, gettext() or dgettext() return msgid.

The normal return value from textdomain() is a pointer to a string containing the current setting of the domain.  If domainname is a null string, textdomain() returns a pointer to the string containing the current domain.  If textdomain() was not previously called and domainname is a NULL pointer, the name of the default domain is returned.  The name of the default domain is messages. 

The return value 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. 

FILES

/usr/lib/locale
The 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

dirname/locale/LC_MESSAGES/domainname.mo
location for file containing messages for domain domainname and path predicate dirname after a successful call to bindtextdomain()

SEE ALSO

msgfmt(1), xgettext(1), setlocale(3C)

NOTES

These routines impose no limit on message length.  However, a text domainname is limited to TEXTDOMAINMAX (256) bytes. 

SunOS 5.1/SPARC  —  Last change: 29 Sep 1992