lib/libintl/gettext.3

   1 .\"     $NetBSD: gettext.3,v 1.10 2004/01/24 16:59:51 wiz 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
  66 The
  67 .Fn gettext ,
  68 .Fn dgettext ,
  69 and
  70 .Fn dcgettext
  71 functions attempt to retrieve a
  72 target string based on the specified
  73 .Fa msgid
  74 argument within the context of a
  75 specific domain and the current locale.
  76 The length of strings returned by
  77 .Fn gettext ,
  78 .Fn dgettext ,
  79 and
  80 .Fn dcgettext
  81 is undetermined until the function is
  82 called.
  83 The
  84 .Fa msgid
  85 argument is a nul-terminated string.
  86 .Pp
  87 The
  88 .Fn ngettext ,
  89 .Fn dngettext ,
  90 and
  91 .Fn dcngettext
  92 functions are equivalent to
  93 .Fn gettext ,
  94 .Fn dgettext ,
  95 and
  96 .Fn dcgettext ,
  97 respectively, except for the handling of
  98 plural forms.
  99 The
 100 .Fn ngettext ,
 101 .Fn dngettext ,
 102 and
 103 .Fn dcngettext
 104 functions search for the
 105 message string using the
 106 .Fa msgid1
 107 argument as the key, using the argument
 108 .Fa n
 109 to
 110 determine the plural form.
 111 If no message catalogs are found,
 112 .Fa msgid1
 113 is returned
 114 if
 115 .Fa n Li == 1 ,
 116 otherwise
 117 .Fa msgid2
 118 is returned.
 119 .Pp
 120 The
 121 .Dv LANGUAGE
 122 environment variable is examined first to determine the message
 123 catalogs to be used.
 124 The value of the
 125 .Dv LANGUAGE
 126 environment variable is a list
 127 of locale names separated by colon (:) character.
 128 If the
 129 .Dv LANGUAGE
 130 environment
 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
 133 returned.
 134 If the
 135 .Dv LANGUAGE
 136 environment variable is defined but failed to locate
 137 a message catalog, the
 138 .Fa msgid
 139 string will be returned.
 140 .Pp
 141 If the
 142 .Dv LANGUAGE
 143 environment variable is not defined,
 144 .Dv LC_ALL ,
 145 .Dv LC_xxx ,
 146 and
 147 .Dv LANG
 148 environment variables are examined to locate the message catalog,
 149 following the convention used by the
 150 .Xr setlocale 3
 151 function.
 152 .Pp
 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
 156 .Fn bindtextdomain ,
 157 locale is a locale name determined by the definition of environment variables,
 158 .Fa category
 159 is
 160 .Dv LC_MESSAGES
 161 if
 162 .Fn gettext ,
 163 .Fn ngettext ,
 164 .Fn dgettext ,
 165 or
 166 .Fn dngettext
 167 is
 168 called, otherwise
 169 .Dv LC_xxx
 170 where the name is the same as the locale category name
 171 specified by the
 172 .Fa category
 173 argument of
 174 .Fn dcgettext
 175 or
 176 .Fn dcngettext .
 177 .Fa domainname
 178 is the name of the domain specified by
 179 .Fn textdomain
 180 or the
 181 .Fa domainname
 182 argument of
 183 .Fn dgettext ,
 184 .Fn dngettext ,
 185 .Fn dcgettext ,
 186 or
 187 .Fn dcngettext .
 188 .Pp
 189 For
 190 .Fn gettext
 191 and
 192 .Fn ngettext ,
 193 the domain used is set by the last valid call to
 194 .Fn textdomain .
 195 If a valid call to
 196 .Fn textdomain
 197 has not been made, the default
 198 domain (called messages) is used.
 199 .Pp
 200 For
 201 .Fn dgettext ,
 202 .Fn dngettext ,
 203 .Fn dcgettext ,
 204 and
 205 .Fn dcngettext ,
 206 the domain used is
 207 specified by the
 208 .Fa domainname
 209 argument.
 210 The
 211 .Fa domainname
 212 argument is equivalent in
 213 syntax and meaning to the
 214 .Fa domainname
 215 argument to
 216 .Fn textdomain ,
 217 except that the
 218 selection of the domain is valid only for the duration of the
 219 .Fn dgettext ,
 220 .Fn dngettext ,
 221 .Fn dcgettext ,
 222 or
 223 .Fn dcngettext
 224 function call.
 225 .Pp
 226 The
 227 .Fn dcgettext
 228 and
 229 .Fn dcngettext
 230 functions require additional argument
 231 .Fa category
 232 for retrieving message string for other than
 233 .Dv LC_MESSAGES
 234 category.
 235 Available value for the
 236 .Fa category
 237 argument are
 238 .Dv LC_CTYPE ,
 239 .Dv LC_COLLATE ,
 240 .Dv LC_MESSAGES ,
 241 .Dv LC_MONETARY ,
 242 .Dv LC_NUMERIC ,
 243 and
 244 .Dv LC_TIME .
 245 The call of
 246 .Fn dcgettext "domainname" "msgid" "LC_MESSAGES"
 247 is equivalent to
 248 .Fn dgettext "domainname" "msgid" .
 249 Note that
 250 .Dv LC_ALL
 251 must not be used.
 252 .Pp
 253 The
 254 .Fn textdomain
 255 function sets or queries the name of the current domain of the
 256 active
 257 .Dv LC_MESSAGES
 258 locale category.
 259 The
 260 .Fa domainname
 261 argument is a
 262 nul-terminated string that can contain only the characters allowed in legal
 263 filenames.
 264 .Pp
 265 The
 266 .Fa domainname
 267 argument is the unique name of a domain on the system.
 268 If there
 269 are multiple versions of the same domain on one system, namespace collisions
 270 can be avoided by using
 271 .Fn bindtextdomain .
 272 If
 273 .Fn textdomain
 274 is not called, a
 275 default domain is selected.
 276 The setting of domain made by the last valid call
 277 to
 278 .Fn textdomain
 279 remains valid across subsequent calls to
 280 .Xr setlocale 3 ,
 281 and
 282 .Fn gettext .
 283 .Pp
 284 The
 285 .Fa domainname
 286 argument is applied to the currently active LC_MESSAGES locale.
 287 .Pp
 288 The current setting of the domain can be queried without affecting the current
 289 state of the domain by calling
 290 .Fn textdomain
 291 with
 292 .Fa domainname
 293 set to the
 294 .Dv NULL
 295 pointer.
 296 Calling
 297 .Fn textdomain
 298 with a
 299 .Fa domainname
 300 argument of a
 301 .Dv NULL
 302 string sets
 303 the domain to the default domain
 304 .Pq messages .
 305 .Pp
 306 The
 307 .Fn bindtextdomain
 308 function binds the path predicate for a message domain
 309 .Fa domainname
 310 to the value contained in dirname.
 311 If
 312 .Fa domainname
 313 is a non-empty
 314 string and has not been bound previously,
 315 .Fn bindtextdomain
 316 binds
 317 .Fa domainname
 318 with
 319 .Fa dirname .
 320 .Pp
 321 If
 322 .Fa domainname
 323 is a non-empty string and has been bound previously,
 324 .Fn bindtextdomain
 325 replaces the old binding with dirname.
 326 The dirname argument
 327 can be an absolute pathname being resolved when
 328 .Fn gettext ,
 329 .Fn ngettext ,
 330 .Fn dgettext ,
 331 .Fn dngettext ,
 332 .Fn dcgettext ,
 333 or
 334 .Fn dcngettext
 335 are called.
 336 If
 337 .Fa domainname
 338 is a
 339 .Dv NULL
 340 pointer or an empty string,
 341 .Fn bindtextdomain
 342 returns a
 343 .Dv NULL
 344 pointer.
 345 If
 346 .Fn bindtextdomain
 347 is not called, implementation-defined default directory is used.
 348 .Pp
 349 The
 350 .Fn bind_textdomain_codeset
 351 function can be used to specify the output
 352 .Fa codeset
 353 for message catalogs for domain
 354 .Fa domainname .
 355 The
 356 .Fa codeset
 357 argument must
 358 be a valid codeset name which can be used for the
 359 .Xr iconv_open 3
 360 function.
 361 .Pp
 362 If the
 363 .Fa codeset
 364 argument is the
 365 .Dv NULL
 366 pointer,
 367 .Fn bind_textdomain_codeset
 368 returns the currently selected
 369 .Fa codeset
 370 for the domain with the name
 371 .Fa domainname .
 372 It returns a
 373 .Dv NULL
 374 pointer if no
 375 .Fa codeset
 376 has yet been selected.
 377 .Pp
 378 The
 379 .Fn bind_textdomain_codeset
 380 function can be used several times.
 381 If used multiple times, with the same
 382 .Fa domainname
 383 argument,
 384 the later call overrides the
 385 settings made by the earlier one.
 386 .Pp
 387 The
 388 .Fn bind_textdomain_codeset
 389 function returns a pointer to a string containing
 390 the 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
 399 The functions are implemented by Citrus project,
 400 based 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
 406 does not work at this moment
 407 .Pq it always fails .