1.\" $NetBSD: gettext.3,v 1.12 2009/11/12 00:43:52 joerg 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 November 10, 2004 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.In libintl.h 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 *msgid1" "const char *msgid2" "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.In libintl.h 60.In locale.h 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 nul-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 104functions search 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, 149following the convention 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 262nul-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 294.Dv NULL 295pointer. 296Calling 297.Fn textdomain 298with a 299.Fa domainname 300argument of a 301.Dv NULL 302string sets 303the domain to the default domain 304.Pq messages . 305.Pp 306The 307.Fn bindtextdomain 308function binds the path predicate for a message domain 309.Fa domainname 310to the value contained in dirname. 311If 312.Fa domainname 313is a non-empty 314string and has not been bound previously, 315.Fn bindtextdomain 316binds 317.Fa domainname 318with 319.Fa dirname . 320.Pp 321If 322.Fa domainname 323is a non-empty string and has been bound previously, 324.Fn bindtextdomain 325replaces the old binding with dirname. 326The dirname argument 327can be an absolute pathname being resolved when 328.Fn gettext , 329.Fn ngettext , 330.Fn dgettext , 331.Fn dngettext , 332.Fn dcgettext , 333or 334.Fn dcngettext 335are called. 336If 337.Fa domainname 338is a 339.Dv NULL 340pointer or an empty string, 341.Fn bindtextdomain 342returns a 343.Dv NULL 344pointer. 345If 346.Fn bindtextdomain 347is not called, implementation-defined default directory is used. 348.Pp 349The 350.Fn bind_textdomain_codeset 351function can be used to specify the output 352.Fa codeset 353for message catalogs for domain 354.Fa domainname . 355The 356.Fa codeset 357argument must 358be a valid codeset name which can be used for the 359.Xr iconv_open 3 360function. 361.Pp 362If the 363.Fa codeset 364argument is the 365.Dv NULL 366pointer, 367.Fn bind_textdomain_codeset 368returns the currently selected 369.Fa codeset 370for the domain with the name 371.Fa domainname . 372It returns a 373.Dv NULL 374pointer if no 375.Fa codeset 376has yet been selected. 377.Pp 378The 379.Fn bind_textdomain_codeset 380function can be used several times. 381If used multiple times, with the same 382.Fa domainname 383argument, 384the later call overrides the 385settings made by the earlier one. 386.Pp 387The 388.Fn bind_textdomain_codeset 389function returns a pointer to a string containing 390the name of the selected 391.Fa codeset . 392.\".Sh "RETURN VALUES" 393.\".Sh EXAMPLES 394.Sh SEE ALSO 395.Xr setlocale 3 , 396.Xr nls 7 397.\".Sh STANDARDS 398.Sh HISTORY 399The functions are implemented by Citrus project, 400based on the documentations for GNU gettext. 401.Sh BUGS 402.\" The text was ripped off from Annex C of 403.\" .Dq LI18NUX 2000 Globalization Specification Version 1.0 . 404.\" .Pp 405.Fn bind_textdomain_codeset 406does not work at this moment 407.Pq it always fails . 408