408 lines
8.8 KiB
Groff
408 lines
8.8 KiB
Groff
.\" $NetBSD: gettext.3,v 1.12 2009/11/12 00:43:52 joerg 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 November 10, 2004
|
|
.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
|
|
.Lb libintl
|
|
.Sh SYNOPSIS
|
|
.In 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 *msgid1" "const char *msgid2" "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"
|
|
.In libintl.h
|
|
.In 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 nul-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
|
|
functions search 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
|
|
nul-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
|
|
.Dv NULL
|
|
pointer.
|
|
Calling
|
|
.Fn textdomain
|
|
with a
|
|
.Fa domainname
|
|
argument of a
|
|
.Dv 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 pathname being resolved when
|
|
.Fn gettext ,
|
|
.Fn ngettext ,
|
|
.Fn dgettext ,
|
|
.Fn dngettext ,
|
|
.Fn dcgettext ,
|
|
or
|
|
.Fn dcngettext
|
|
are called.
|
|
If
|
|
.Fa domainname
|
|
is a
|
|
.Dv NULL
|
|
pointer or an empty string,
|
|
.Fn bindtextdomain
|
|
returns a
|
|
.Dv 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
|
|
.Dv NULL
|
|
pointer,
|
|
.Fn bind_textdomain_codeset
|
|
returns the currently selected
|
|
.Fa codeset
|
|
for the domain with the name
|
|
.Fa domainname .
|
|
It returns a
|
|
.Dv 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 ,
|
|
.Xr nls 7
|
|
.\".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 .
|
|
.\" .Pp
|
|
.Fn bind_textdomain_codeset
|
|
does not work at this moment
|
|
.Pq it always fails .
|