summaryrefslogtreecommitdiff
path: root/lib/libintl/gettext.3
diff options
context:
space:
mode:
authoritojun <itojun@NetBSD.org>2000-10-31 10:45:04 +0000
committeritojun <itojun@NetBSD.org>2000-10-31 10:45:04 +0000
commitbb42e65bfecc3a76253c9b8889051cfe941a4b9a (patch)
treea911cb364c6dead82bf2de14b4bf9ca7ac12aa48 /lib/libintl/gettext.3
parentef28de501182943a2433b9a2fd6127dafe6e3583 (diff)
BSD-licensed libintl, fully compatible with GNU libintl (in GNU gettext).
from Citrus project xpg4dl repository.
Diffstat (limited to 'lib/libintl/gettext.3')
-rw-r--r--lib/libintl/gettext.3390
1 files changed, 390 insertions, 0 deletions
diff --git a/lib/libintl/gettext.3 b/lib/libintl/gettext.3
new file mode 100644
index 00000000000..12862c72859
--- /dev/null
+++ b/lib/libintl/gettext.3
@@ -0,0 +1,390 @@
+.\" $NetBSD: gettext.3,v 1.1.1.1 2000/10/31 10:45:05 itojun Exp $
+.\"
+.\" Copyright (c) 2000 Citrus Project,
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd October 20, 2000
+.Dt GETTEXT 3
+.Os
+.Sh NAME
+.Nm gettext ,
+.Nm dgettext ,
+.Nm ngettext ,
+.Nm dngettext ,
+.Nm textdomain ,
+.Nm bindtextdomain ,
+.Nm bind_textdomain_codeset ,
+.Nm dcgettext ,
+.Nm dcngettext
+.Nd message handling functions
+.Sh LIBRARY
+libintl
+.Sh SYNOPSIS
+.Fd #include <libintl.h>
+.Ft char *
+.Fn gettext "const char *msgid"
+.Ft char *
+.Fn dgettext "const char *domainname" "const char *msgid"
+.Ft char *
+.Fn ngettext "const char *domainname" "const char *msgid" "unsigned long int n"
+.Ft char *
+.Fn dngettext "const char *domainname" "const char *msgid1" "const char *msgid2" "unsigned long int n"
+.Ft char *
+.Fn textdomain "const char *domainname"
+.Ft char *
+.Fn bindtextdomain "const char *domainname" "const char *dirname"
+.Ft char *
+.Fn bind_textdomain_codeset "const char *domainname" "const char *codeset"
+.Fd #include <libintl.h>
+.Fd #include <locale.h>
+.Ft char *
+.Fn dcgettext "const char *domainname" "const char *msgid" "int category"
+.Ft char *
+.Fn dcngettext "const char *domainname" "const char *msgid1" "const char *msgid2" "unsigned long int n" "int category"
+.Sh DESCRIPTION
+The
+.Fn gettext ,
+.Fn dgettext ,
+and
+.Fn dcgettext
+functions attempt to retrieve a
+target string based on the specified
+.Fa msgid
+argument within the context of a
+specific domain and the current locale.
+The length of strings returned by
+.Fn gettext ,
+.Fn dgettext ,
+and
+.fn dcgettext
+is undetermined until the function is
+called.
+The
+.Fa msgid
+argument is a null-terminated string.
+.Pp
+The
+.Fn ngettext ,
+.Fn dngettext
+and
+.Fn dcngettext
+functions are equivalent to
+.Fn gettext ,
+.Fn dgettext
+and
+.Fn dcgettext ,
+respectively, except for the handling of
+plural forms.
+The
+.Fn ngettext ,
+.Fn dngettext
+and
+.Fn dcngettext
+searches for the
+message string using the
+.Fa msgid1
+argument as the key, using the argument
+.Fa n
+to
+determine the plural form.
+If no message catalogs are found,
+.Fa msgid1
+is returned
+if
+.Fa n Li == 1 ,
+otherwise
+.Fa msgid2
+is returned.
+.Pp
+The
+.Dv LANGUAGE
+environment variable is examined first to determine the message
+catalogs to be used.
+The value of the
+.Dv LANGUAGE
+environment variable is a list
+of locale names separated by colon (:) character.
+If the
+.Dv 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
+.Dv LANGUAGE
+environment variable is defined but failed to locate
+a message catalog, the
+.Fa msgid
+string will be returned.
+.Pp
+If the
+.Dv LANGUAGE
+environment variable is not defined,
+.Dv LC_ALL ,
+.Dv LC_xxx
+and
+.Dv LANG
+environment variables are examined to locate the message catalog, following the
+convention used by the
+.Xr setlocale 3
+function.
+.Pp
+The pathname used to locate the message catalog is
+.Pa dirname/locale/category/domainname.mo,
+where dirname is the directory specified by
+.Fn bindtextdomain ,
+locale is a locale name determined by the definition of environment variables,
+.Fa category
+is
+.Dv LC_MESSAGES
+if
+.Fn gettext ,
+.Fn ngettext ,
+.Fn dgettext
+or
+.Fn dngettext
+is
+called, otherwise
+.Dv LC_xxx
+where the name is the same as the locale category name
+specified by the
+.Fa category
+argument of
+.Fn dcgettext
+or
+.Fn dcngettext .
+.Fa domainname
+is the name of the domain specified by
+.Fn textdomain
+or the
+.Fa domainname
+argument of
+.Fn dgettext ,
+.Fn dngettext ,
+.Fn dcgettext
+or
+.Fn dcngettext .
+.Pp
+For
+.Fn gettext
+and
+.Fn ngettext ,
+the domain used is set by the last valid call to
+.Fn textdomain .
+If a valid call to
+.Fn textdomain
+has not been made, the default
+domain (called messages) is used.
+.Pp
+For
+.Fn dgettext ,
+.Fn dngettext ,
+.Fn dcgettext
+and
+.Fn dcngettext ,
+the domain used is
+specified by the
+.Fa domainname
+argument.
+The
+.Fa domainname
+argument is equivalent in
+syntax and meaning to the
+.Fa domainname
+argument to
+.Fn textdomain ,
+except that the
+selection of the domain is valid only for the duration of the
+.Fn dgettext ,
+.Fn dngettext ,
+.Fn dcgettext
+or
+.Fn dcngettext
+function call.
+.Pp
+The
+.Fn dcgettext
+and
+.Fn dcngettext
+functions require additional argument
+.Fa category
+for retrieving message string for other than
+.Dv LC_MESSAGES
+category.
+Available value for the
+.Fa category
+argument are
+.Dv LC_CTYPE ,
+.Dv LC_COLLATE ,
+.Dv LC_MESSAGES ,
+.Dv LC_MONETARY ,
+.Dv LC_NUMERIC
+and
+.Dv LC_TIME .
+The call of
+.Fn dcgettext "domainname" "msgid" "LC_MESSAGES"
+is equivalent to
+.Fn dgettext "domainname" "msgid" .
+Note that
+.Dv LC_ALL
+must not be used.
+.Pp
+The
+.Fn textdomain
+function sets or queries the name of the current domain of the
+active
+.Dv LC_MESSAGES
+locale category.
+The
+.Fa domainname
+argument is a
+null-terminated string that can contain only the characters allowed in legal
+filenames.
+.Pp
+The
+.Fa 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
+.Fn bindtextdomain .
+If
+.Fn textdomain
+is not called, a
+default domain is selected.
+The setting of domain made by the last valid call
+to
+.Fn textdomain
+remains valid across subsequent calls to
+.Xr setlocale 3 ,
+and
+.Fn gettext .
+.Pp
+The
+.Fa domainname
+argument is applied to the currently active LC_MESSAGES locale.
+.Pp
+The current setting of the domain can be queried without affecting the current
+state of the domain by calling
+.Fn textdomain
+with
+.Fa domainname
+set to the null pointer.
+Calling
+.Fn textdomain
+with a
+.Fa domainname
+argument of a null string sets
+the domain to the default domain
+.Pq messages .
+.Pp
+The
+.Fn bindtextdomain
+function binds the path predicate for a message domain
+.Fa domainname
+to the value contained in dirname.
+If
+.Fa domainname
+is a non-empty
+string and has not been bound previously,
+.Fn bindtextdomain
+binds
+.Fa domainname
+with
+.Fa dirname .
+.Pp
+If
+.Fa domainname
+is a non-empty string and has been bound previously,
+.Fn bindtextdomain
+replaces the old binding with dirname.
+The dirname argument
+can be an absolute or relative pathname being resolved when
+.Fn gettext ,
+.Fn ngettext ,
+.Fn dgettext ,
+.Fn dngettext ,
+.Fn dcgettext ,
+or
+.Fn dcngettext
+are called.
+If
+.Fa domainname
+is a null pointer or an empty string,
+.Fn bindtextdomain
+returns null pointer.
+If
+.Fn bindtextdomain
+is not called, implementation-defined default directory is used.
+.Pp
+The
+.Fn bind_textdomain_codeset
+function can be used to specify the output
+.Fa codeset
+for message catalogs for domain
+.Fa domainname .
+The
+.Fa codeset
+argument must
+be a valid codeset name which can be used for the
+.Xr iconv_open 3
+function.
+.Pp
+If the
+.Fa codeset
+argument is the null pointer,
+.Fn bind_textdomain_codeset
+returns the currently selected
+.Fa codeset
+for the domain with the name
+.Fa domainname .
+It returns null pointer if no
+.Fa codeset
+has yet been selected.
+.Pp
+The
+.Fn bind_textdomain_codeset
+function can be used several times.
+If used multiple times, with the same
+.Fa domainname
+argument,
+the later call overrides the
+settings made by the earlier one.
+.Pp
+The
+.Fn bind_textdomain_codeset
+function returns a pointer to a string containing
+the name of the selected
+.Fa codeset .
+.\".Sh "RETURN VALUES"
+.\".Sh EXAMPLES
+.Sh SEE ALSO
+.Xr setlocale 3
+.\".Sh STANDARDS
+.Sh HISTORY
+The functions are implemented by Citrus project,
+based on the documentations for GNU gettext.
+.Sh BUGS
+The text was ripped off from Annex C of
+.Dq LI18NUX 2000 Globalization Specification Version 1.0 .