1 .\" $NetBSD: gettext.3,v 1.12 2009/11/12 00:43:52 joerg Exp $
3 .\" Copyright (c) 2000 Citrus Project,
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nm bind_textdomain_codeset ,
40 .Nd message handling functions
46 .Fn gettext "const char *msgid"
48 .Fn dgettext "const char *domainname" "const char *msgid"
50 .Fn ngettext "const char *msgid1" "const char *msgid2" "unsigned long int n"
52 .Fn dngettext "const char *domainname" "const char *msgid1" "const char *msgid2" "unsigned long int n"
54 .Fn textdomain "const char *domainname"
56 .Fn bindtextdomain "const char *domainname" "const char *dirname"
58 .Fn bind_textdomain_codeset "const char *domainname" "const char *codeset"
62 .Fn dcgettext "const char *domainname" "const char *msgid" "int category"
64 .Fn dcngettext "const char *domainname" "const char *msgid1" "const char *msgid2" "unsigned long int n" "int category"
71 functions attempt to retrieve a
72 target string based on the specified
74 argument within the context of a
75 specific domain and the current locale.
76 The length of strings returned by
81 is undetermined until the function is
85 argument is a nul-terminated string.
92 functions are equivalent to
97 respectively, except for the handling of
104 functions search for the
105 message string using the
107 argument as the key, using the argument
110 determine the plural form.
111 If no message catalogs are found,
122 environment variable is examined first to determine the message
126 environment variable is a list
127 of locale names separated by colon (:) character.
131 variable is defined, each locale name is tried in the specified order and if a
132 message catalog containing the requested message is found, the message is
136 environment variable is defined but failed to locate
137 a message catalog, the
139 string will be returned.
143 environment variable is not defined,
148 environment variables are examined to locate the message catalog,
149 following the convention used by the
153 The pathname used to locate the message catalog is
154 .Pa dirname/locale/category/domainname.mo ,
155 where dirname is the directory specified by
157 locale is a locale name determined by the definition of environment variables,
170 where the name is the same as the locale category name
178 is the name of the domain specified by
193 the domain used is set by the last valid call to
197 has not been made, the default
198 domain (called messages) is used.
212 argument is equivalent in
213 syntax and meaning to the
218 selection of the domain is valid only for the duration of the
230 functions require additional argument
232 for retrieving message string for other than
235 Available value for the
246 .Fn dcgettext "domainname" "msgid" "LC_MESSAGES"
248 .Fn dgettext "domainname" "msgid" .
255 function sets or queries the name of the current domain of the
262 nul-terminated string that can contain only the characters allowed in legal
267 argument is the unique name of a domain on the system.
269 are multiple versions of the same domain on one system, namespace collisions
270 can be avoided by using
275 default domain is selected.
276 The setting of domain made by the last valid call
279 remains valid across subsequent calls to
286 argument is applied to the currently active LC_MESSAGES locale.
288 The current setting of the domain can be queried without affecting the current
289 state of the domain by calling
303 the domain to the default domain
308 function binds the path predicate for a message domain
310 to the value contained in dirname.
314 string and has not been bound previously,
323 is a non-empty string and has been bound previously,
325 replaces the old binding with dirname.
327 can be an absolute pathname being resolved when
340 pointer or an empty string,
347 is not called, implementation-defined default directory is used.
350 .Fn bind_textdomain_codeset
351 function can be used to specify the output
353 for message catalogs for domain
358 be a valid codeset name which can be used for the
367 .Fn bind_textdomain_codeset
368 returns the currently selected
370 for the domain with the name
376 has yet been selected.
379 .Fn bind_textdomain_codeset
380 function can be used several times.
381 If used multiple times, with the same
384 the later call overrides the
385 settings made by the earlier one.
388 .Fn bind_textdomain_codeset
389 function returns a pointer to a string containing
390 the name of the selected
392 .\".Sh "RETURN VALUES"
399 The functions are implemented by Citrus project,
400 based on the documentations for GNU gettext.
402 .\" The text was ripped off from Annex C of
403 .\" .Dq LI18NUX 2000 Globalization Specification Version 1.0 .
405 .Fn bind_textdomain_codeset
406 does not work at this moment
407 .Pq it always fails .