gettext(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
GETTEXT(3)              NetBSD Library Functions Manual             GETTEXT(3)


NAME

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


LIBRARY

     Internationalized Message Handling Library (libintl, -lintl)


SYNOPSIS

     #include <libintl.h>

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

     #include <libintl.h>
     #include <locale.h>

     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 han-
     dling 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 mes-
     sage 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 argu-
     ment 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 cate-
     gory.  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 con-
     taining the name of the selected codeset.


SEE ALSO

     setlocale(3), nls(7)


HISTORY

     The functions are implemented by Citrus project, based on the documenta-
     tions for GNU gettext.


BUGS

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

NetBSD 5.0                     November 10, 2004                    NetBSD 5.0