1.\" $NetBSD: gettext.3,v 1.6 2002/02/07 07:00:47 ross Exp $ 2.\" 3.\" Copyright (c) 2000 Citrus Project, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 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. 14.\" 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 25.\" SUCH DAMAGE. 26.\" 27.Dd October 20, 2000 28.Dt GETTEXT 3 29.Os 30.Sh NAME 31.Nm gettext , 32.Nm dgettext , 33.Nm ngettext , 34.Nm dngettext , 35.Nm textdomain , 36.Nm bindtextdomain , 37.Nm bind_textdomain_codeset , 38.Nm dcgettext , 39.Nm dcngettext 40.Nd message handling functions 41.Sh LIBRARY 42.Lb libintl 43.Sh SYNOPSIS 44.Fd #include \*[Lt]libintl.h\*[Gt] 45.Ft char * 46.Fn gettext "const char *msgid" 47.Ft char * 48.Fn dgettext "const char *domainname" "const char *msgid" 49.Ft char * 50.Fn ngettext "const char *domainname" "const char *msgid" "unsigned long int n" 51.Ft char * 52.Fn dngettext "const char *domainname" "const char *msgid1" "const char *msgid2" "unsigned long int n" 53.Ft char * 54.Fn textdomain "const char *domainname" 55.Ft char * 56.Fn bindtextdomain "const char *domainname" "const char *dirname" 57.Ft char * 58.Fn bind_textdomain_codeset "const char *domainname" "const char *codeset" 59.Fd #include \*[Lt]libintl.h\*[Gt] 60.Fd #include \*[Lt]locale.h\*[Gt] 61.Ft char * 62.Fn dcgettext "const char *domainname" "const char *msgid" "int category" 63.Ft char * 64.Fn dcngettext "const char *domainname" "const char *msgid1" "const char *msgid2" "unsigned long int n" "int category" 65.Sh DESCRIPTION 66The 67.Fn gettext , 68.Fn dgettext , 69and 70.Fn dcgettext 71functions attempt to retrieve a 72target string based on the specified 73.Fa msgid 74argument within the context of a 75specific domain and the current locale. 76The length of strings returned by 77.Fn gettext , 78.Fn dgettext , 79and 80.fn dcgettext 81is undetermined until the function is 82called. 83The 84.Fa msgid 85argument is a null-terminated string. 86.Pp 87The 88.Fn ngettext , 89.Fn dngettext 90and 91.Fn dcngettext 92functions are equivalent to 93.Fn gettext , 94.Fn dgettext 95and 96.Fn dcgettext , 97respectively, except for the handling of 98plural forms. 99The 100.Fn ngettext , 101.Fn dngettext 102and 103.Fn dcngettext 104searches for the 105message string using the 106.Fa msgid1 107argument as the key, using the argument 108.Fa n 109to 110determine the plural form. 111If no message catalogs are found, 112.Fa msgid1 113is returned 114if 115.Fa n Li == 1 , 116otherwise 117.Fa msgid2 118is returned. 119.Pp 120The 121.Dv LANGUAGE 122environment variable is examined first to determine the message 123catalogs to be used. 124The value of the 125.Dv LANGUAGE 126environment variable is a list 127of locale names separated by colon (:) character. 128If the 129.Dv LANGUAGE 130environment 131variable is defined, each locale name is tried in the specified order and if a 132message catalog containing the requested message is found, the message is 133returned. 134If the 135.Dv LANGUAGE 136environment variable is defined but failed to locate 137a message catalog, the 138.Fa msgid 139string will be returned. 140.Pp 141If the 142.Dv LANGUAGE 143environment variable is not defined, 144.Dv LC_ALL , 145.Dv LC_xxx 146and 147.Dv LANG 148environment variables are examined to locate the message catalog, following the 149convention used by the 150.Xr setlocale 3 151function. 152.Pp 153The pathname used to locate the message catalog is 154.Pa dirname/locale/category/domainname.mo, 155where dirname is the directory specified by 156.Fn bindtextdomain , 157locale is a locale name determined by the definition of environment variables, 158.Fa category 159is 160.Dv LC_MESSAGES 161if 162.Fn gettext , 163.Fn ngettext , 164.Fn dgettext 165or 166.Fn dngettext 167is 168called, otherwise 169.Dv LC_xxx 170where the name is the same as the locale category name 171specified by the 172.Fa category 173argument of 174.Fn dcgettext 175or 176.Fn dcngettext . 177.Fa domainname 178is the name of the domain specified by 179.Fn textdomain 180or the 181.Fa domainname 182argument of 183.Fn dgettext , 184.Fn dngettext , 185.Fn dcgettext 186or 187.Fn dcngettext . 188.Pp 189For 190.Fn gettext 191and 192.Fn ngettext , 193the domain used is set by the last valid call to 194.Fn textdomain . 195If a valid call to 196.Fn textdomain 197has not been made, the default 198domain (called messages) is used. 199.Pp 200For 201.Fn dgettext , 202.Fn dngettext , 203.Fn dcgettext 204and 205.Fn dcngettext , 206the domain used is 207specified by the 208.Fa domainname 209argument. 210The 211.Fa domainname 212argument is equivalent in 213syntax and meaning to the 214.Fa domainname 215argument to 216.Fn textdomain , 217except that the 218selection of the domain is valid only for the duration of the 219.Fn dgettext , 220.Fn dngettext , 221.Fn dcgettext 222or 223.Fn dcngettext 224function call. 225.Pp 226The 227.Fn dcgettext 228and 229.Fn dcngettext 230functions require additional argument 231.Fa category 232for retrieving message string for other than 233.Dv LC_MESSAGES 234category. 235Available value for the 236.Fa category 237argument are 238.Dv LC_CTYPE , 239.Dv LC_COLLATE , 240.Dv LC_MESSAGES , 241.Dv LC_MONETARY , 242.Dv LC_NUMERIC 243and 244.Dv LC_TIME . 245The call of 246.Fn dcgettext "domainname" "msgid" "LC_MESSAGES" 247is equivalent to 248.Fn dgettext "domainname" "msgid" . 249Note that 250.Dv LC_ALL 251must not be used. 252.Pp 253The 254.Fn textdomain 255function sets or queries the name of the current domain of the 256active 257.Dv LC_MESSAGES 258locale category. 259The 260.Fa domainname 261argument is a 262null-terminated string that can contain only the characters allowed in legal 263filenames. 264.Pp 265The 266.Fa domainname 267argument is the unique name of a domain on the system. 268If there 269are multiple versions of the same domain on one system, namespace collisions 270can be avoided by using 271.Fn bindtextdomain . 272If 273.Fn textdomain 274is not called, a 275default domain is selected. 276The setting of domain made by the last valid call 277to 278.Fn textdomain 279remains valid across subsequent calls to 280.Xr setlocale 3 , 281and 282.Fn gettext . 283.Pp 284The 285.Fa domainname 286argument is applied to the currently active LC_MESSAGES locale. 287.Pp 288The current setting of the domain can be queried without affecting the current 289state of the domain by calling 290.Fn textdomain 291with 292.Fa domainname 293set to the null pointer. 294Calling 295.Fn textdomain 296with a 297.Fa domainname 298argument of a null string sets 299the domain to the default domain 300.Pq messages . 301.Pp 302The 303.Fn bindtextdomain 304function binds the path predicate for a message domain 305.Fa domainname 306to the value contained in dirname. 307If 308.Fa domainname 309is a non-empty 310string and has not been bound previously, 311.Fn bindtextdomain 312binds 313.Fa domainname 314with 315.Fa dirname . 316.Pp 317If 318.Fa domainname 319is a non-empty string and has been bound previously, 320.Fn bindtextdomain 321replaces the old binding with dirname. 322The dirname argument 323can be an absolute pathname being resolved when 324.Fn gettext , 325.Fn ngettext , 326.Fn dgettext , 327.Fn dngettext , 328.Fn dcgettext , 329or 330.Fn dcngettext 331are called. 332If 333.Fa domainname 334is a null pointer or an empty string, 335.Fn bindtextdomain 336returns null pointer. 337If 338.Fn bindtextdomain 339is not called, implementation-defined default directory is used. 340.Pp 341The 342.Fn bind_textdomain_codeset 343function can be used to specify the output 344.Fa codeset 345for message catalogs for domain 346.Fa domainname . 347The 348.Fa codeset 349argument must 350be a valid codeset name which can be used for the 351.Xr iconv_open 3 352function. 353.Pp 354If the 355.Fa codeset 356argument is the null pointer, 357.Fn bind_textdomain_codeset 358returns the currently selected 359.Fa codeset 360for the domain with the name 361.Fa domainname . 362It returns null pointer if no 363.Fa codeset 364has yet been selected. 365.Pp 366The 367.Fn bind_textdomain_codeset 368function can be used several times. 369If used multiple times, with the same 370.Fa domainname 371argument, 372the later call overrides the 373settings made by the earlier one. 374.Pp 375The 376.Fn bind_textdomain_codeset 377function returns a pointer to a string containing 378the name of the selected 379.Fa codeset . 380.\".Sh "RETURN VALUES" 381.\".Sh EXAMPLES 382.Sh SEE ALSO 383.Xr setlocale 3 384.\".Sh STANDARDS 385.Sh HISTORY 386The functions are implemented by Citrus project, 387based on the documentations for GNU gettext. 388.Sh BUGS 389The text was ripped off from Annex C of 390.Dq LI18NUX 2000 Globalization Specification Version 1.0 . 391.Pp 392.Fn bind_textdomain_codeset 393does not work at this moment 394.Pq always fail . 395