\"      $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 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.