Sync em(4) manpage with the one in Intel em 6.2.9
[dragonfly.git] / share / man / man7 / nls.7
1 .\"     $NetBSD: nls.7,v 1.11 2003/06/26 11:55:56 wiz Exp $
2 .\"
3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\"    notice, this list of conditions and the following disclaimer in the
16 .\"    documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"        This product includes software developed by the NetBSD
20 .\"        Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\"    contributors may be used to endorse or promote products derived
23 .\"    from this software without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\"
37 .\" $DragonFly: src/share/man/man7/nls.7,v 1.5 2006/10/14 23:59:59 swildner Exp $
38 .\"
39 .Dd May 17, 2003
40 .Dt NLS 7
41 .Os
42 .Sh NAME
43 .Nm NLS
44 .Nd Native Language Support Overview
45 .Sh DESCRIPTION
46 Native Language Support (NLS) provides commands for a single
47 worldwide operating system base.
48 An internationalized system has no built-in assumptions or dependencies
49 on language-specific or cultural-specific conventions such as:
50 .Pp
51 .Bl -bullet -offset indent -compact
52 .It
53 Character classifications
54 .It
55 Character comparison rules
56 .It
57 Character collation order
58 .It
59 Numeric and monetary formatting
60 .It
61 Date and time formatting
62 .It
63 Message-text language
64 .It
65 Character sets
66 .El
67 .Pp
68 All information pertaining to cultural conventions and language is
69 obtained at program run time.
70 .Pp
71 .Dq Internationalization
72 (often abbreviated
73 .Dq i18n )
74 refers to the operation by which system software is developed to support
75 multiple cultural-specific and language-specific conventions.
76 This is a generalization process by which the system is untied from
77 calling only English strings or other English-specific conventions.
78 .Dq Localization
79 (often abbreviated
80 .Dq l10n )
81 refers to the operations by which the user environment is customized to
82 handle its input and output appropriate for specific language and cultural
83 conventions.
84 This is a specialization process, by which generic methods already
85 implemented in an internationalized system are used in specific ways.
86 The formal description of cultural conventions for some country, together
87 with all associated translations targeted to the native language, is
88 called the
89 .Dq locale .
90 .Pp
91 .Dx
92 provides extensive support to programmers and system developers to
93 enable internationalized software to be developed.
94 .Dx
95 also supplies a large variety of locales for system localization.
96 .Ss Localization of Information
97 All locale information is accessible to programs at run time so that
98 data is processed and displayed correctly for specific cultural
99 conventions and language.
100 .Pp
101 A locale is divided into categories.
102 A category is a group of language-specific and culture-specific conventions
103 as outlined in the list above.
104 ISO C specifies the following six standard categories supported by
105 .Dx :
106 .Pp
107 .Bl -tag -compact -width LC_MONETARYXX
108 .It LC_COLLATE
109 string-collation order information
110 .It LC_CTYPE
111 character classification, case conversion, and other character attributes
112 .It LC_MESSAGES
113 the format for affirmative and negative responses
114 .It LC_MONETARY
115 rules and symbols for formatting monetary numeric information
116 .It LC_NUMERIC
117 rules and symbols for formatting nonmonetary numeric information
118 .It LC_TIME
119 rules and symbols for formatting time and date information
120 .El
121 .Pp
122 Localization of the system is achieved by setting appropriate values
123 in environment variables to identify which locale should be used.
124 The environment variables have the same names as their respective
125 locale categories.
126 Additionally, the
127 .Ev LANG ,
128 .Ev LC_ALL ,
129 and
130 .Ev NLSPATH
131 environment variables are used.
132 The
133 .Ev NLSPATH
134 environment variable specifies a colon-separated list of directory names
135 where the message catalog files of the NLS database are located.
136 The
137 .Ev LC_ALL
138 and
139 .Ev LANG
140 environment variables also determine the current locale.
141 .Pp
142 The values of these environment variables contains a string format as:
143 .Pp
144 .Bd -literal
145         language[_territory][.codeset][@modifier]
146 .Ed
147 .Pp
148 Valid values for the language field come from the ISO639 standard which
149 defines two-character codes for many languages.
150 Some common language codes are:
151 .Pp
152 .nf
153 .ta \w'SERBO-CROATIAN'u+2n +\w'DE'u+5n +\w'OCEANIC/INDONESIAN'u+2nC
154 \fILanguage Name\fP     \fICode\fP      \fILanguage Family\fP
155 .ta \w'SERBO-CROATIAN'u+2n +\w'DE'u+5n +\w'OCEANIC/INDONESIAN'u+2nC
156 .sp 5p
157 ABKHAZIAN       AB      IBERO-CAUCASIAN
158 AFAN (OROMO)    OM      HAMITIC
159 AFAR    AA      HAMITIC
160 AFRIKAANS       AF      GERMANIC
161 ALBANIAN        SQ      INDO-EUROPEAN (OTHER)
162 AMHARIC AM      SEMITIC
163 ARABIC  AR      SEMITIC
164 ARMENIAN        HY      INDO-EUROPEAN (OTHER)
165 ASSAMESE        AS      INDIAN
166 AYMARA  AY      AMERINDIAN
167 AZERBAIJANI     AZ      TURKIC/ALTAIC
168 BASHKIR BA      TURKIC/ALTAIC
169 BASQUE  EU      BASQUE
170 BENGALI BN      INDIAN
171 BHUTANI DZ      ASIAN
172 BIHARI  BH      INDIAN
173 BISLAMA BI
174 BRETON  BR      CELTIC
175 BULGARIAN       BG      SLAVIC
176 BURMESE MY      ASIAN
177 BYELORUSSIAN    BE      SLAVIC
178 CAMBODIAN       KM      ASIAN
179 CATALAN CA      ROMANCE
180 CHINESE ZH      ASIAN
181 CORSICAN        CO      ROMANCE
182 CROATIAN        HR      SLAVIC
183 CZECH   CS      SLAVIC
184 DANISH  DA      GERMANIC
185 DUTCH   NL      GERMANIC
186 ENGLISH EN      GERMANIC
187 ESPERANTO       EO      INTERNATIONAL AUX.
188 ESTONIAN        ET      FINNO-UGRIC
189 FAROESE FO      GERMANIC
190 FIJI    FJ      OCEANIC/INDONESIAN
191 FINNISH FI      FINNO-UGRIC
192 FRENCH  FR      ROMANCE
193 FRISIAN FY      GERMANIC
194 GALICIAN        GL      ROMANCE
195 GEORGIAN        KA      IBERO-CAUCASIAN
196 GERMAN  DE      GERMANIC
197 GREEK   EL      LATIN/GREEK
198 GREENLANDIC     KL      ESKIMO
199 GUARANI GN      AMERINDIAN
200 GUJARATI        GU      INDIAN
201 HAUSA   HA      NEGRO-AFRICAN
202 HEBREW  HE      SEMITIC
203 HINDI   HI      INDIAN
204 HUNGARIAN       HU      FINNO-UGRIC
205 ICELANDIC       IS      GERMANIC
206 INDONESIAN      ID      OCEANIC/INDONESIAN
207 INTERLINGUA     IA      INTERNATIONAL AUX.
208 INTERLINGUE     IE      INTERNATIONAL AUX.
209 INUKTITUT       IU
210 INUPIAK IK      ESKIMO
211 IRISH   GA      CELTIC
212 ITALIAN IT      ROMANCE
213 JAPANESE        JA      ASIAN
214 JAVANESE        JV      OCEANIC/INDONESIAN
215 KANNADA KN      DRAVIDIAN
216 KASHMIRI        KS      INDIAN
217 KAZAKH  KK      TURKIC/ALTAIC
218 KINYARWANDA     RW      NEGRO-AFRICAN
219 KIRGHIZ KY      TURKIC/ALTAIC
220 KURUNDI RN      NEGRO-AFRICAN
221 KOREAN  KO      ASIAN
222 KURDISH KU      IRANIAN
223 LAOTHIAN        LO      ASIAN
224 LATIN   LA      LATIN/GREEK
225 LATVIAN LV      BALTIC
226 LINGALA LN      NEGRO-AFRICAN
227 LITHUANIAN      LT      BALTIC
228 MACEDONIAN      MK      SLAVIC
229 MALAGASY        MG      OCEANIC/INDONESIAN
230 MALAY   MS      OCEANIC/INDONESIAN
231 MALAYALAM       ML      DRAVIDIAN
232 MALTESE MT      SEMITIC
233 MAORI   MI      OCEANIC/INDONESIAN
234 MARATHI MR      INDIAN
235 MOLDAVIAN       MO      ROMANCE
236 MONGOLIAN       MN
237 NAURU   NA
238 NEPALI  NE      INDIAN
239 NORWEGIAN       NO      GERMANIC
240 OCCITAN OC      ROMANCE
241 ORIYA   OR      INDIAN
242 PASHTO  PS      IRANIAN
243 PERSIAN (farsi) FA      IRANIAN
244 POLISH  PL      SLAVIC
245 PORTUGUESE      PT      ROMANCE
246 PUNJABI PA      INDIAN
247 QUECHUA QU      AMERINDIAN
248 RHAETO-ROMANCE  RM      ROMANCE
249 ROMANIAN        RO      ROMANCE
250 RUSSIAN RU      SLAVIC
251 SAMOAN  SM      OCEANIC/INDONESIAN
252 SANGHO  SG      NEGRO-AFRICAN
253 SANSKRIT        SA      INDIAN
254 SCOTS GAELIC    GD      CELTIC
255 SERBIAN SR      SLAVIC
256 SERBO-CROATIAN  SH      SLAVIC
257 SESOTHO ST      NEGRO-AFRICAN
258 SETSWANA        TN      NEGRO-AFRICAN
259 SHONA   SN      NEGRO-AFRICAN
260 SINDHI  SD      INDIAN
261 SINGHALESE      SI      INDIAN
262 SISWATI SS      NEGRO-AFRICAN
263 SLOVAK  SK      SLAVIC
264 SLOVENIAN       SL      SLAVIC
265 SOMALI  SO      HAMITIC
266 SPANISH ES      ROMANCE
267 SUNDANESE       SU      OCEANIC/INDONESIAN
268 SWAHILI SW      NEGRO-AFRICAN
269 SWEDISH SV      GERMANIC
270 TAGALOG TL      OCEANIC/INDONESIAN
271 TAJIK   TG      IRANIAN
272 TAMIL   TA      DRAVIDIAN
273 TATAR   TT      TURKIC/ALTAIC
274 TELUGU  TE      DRAVIDIAN
275 THAI    TH      ASIAN
276 TIBETAN BO      ASIAN
277 TIGRINYA        TI      SEMITIC
278 TONGA   TO      OCEANIC/INDONESIAN
279 TSONGA  TS      NEGRO-AFRICAN
280 TURKISH TR      TURKIC/ALTAIC
281 TURKMEN TK      TURKIC/ALTAIC
282 TWI     TW      NEGRO-AFRICAN
283 UIGUR   UG
284 UKRAINIAN       UK      SLAVIC
285 URDU    UR      INDIAN
286 UZBEK   UZ      TURKIC/ALTAIC
287 VIETNAMESE      VI      ASIAN
288 VOLAPUK VO      INTERNATIONAL AUX.
289 WELSH   CY      CELTIC
290 WOLOF   WO      NEGRO-AFRICAN
291 XHOSA   XH      NEGRO-AFRICAN
292 YIDDISH YI      GERMANIC
293 YORUBA  YO      NEGRO-AFRICAN
294 ZHUANG  ZA
295 ZULU    ZU      NEGRO-AFRICAN
296 .ta
297 .fi
298 .Pp
299 For example, the locale for the Danish language spoken in Denmark
300 using the ISO8859-1 character set is da_DK.ISO8859-1.
301 The da stands for the Danish language and the DK stands for Denmark.
302 The short form of da_DK is sufficient to indicate this locale.
303 .Pp
304 The environment variable settings are queried by their priority level
305 in the following manner:
306 .Pp
307 .Bl -bullet
308 .It
309 If the
310 .Ev LC_ALL
311 environment variable is set, all six categories use the locale it
312 specifies.
313 .It
314 If the
315 .Ev LC_ALL
316 environment variable is not set, each individual category uses the
317 locale specified by its corresponding environment variable.
318 .It
319 If the
320 .Ev LC_ALL
321 environment variable is not set, and a value for a particular
322 .Ev LC_*
323 environment variable is not set, the value of the
324 .Ev LANG
325 environment variable specifies the default locale for all categories.
326 Only the
327 .Ev LANG
328 environment variable should be set in /etc/profile, since it makes it
329 most easy for the user to override the system default using the individual
330 .Ev LC_*
331 variables.
332 .It
333 If the
334 .Ev LC_ALL
335 environment variable is not set, a value for a particular
336 .Ev LC_*
337 environment variable is not set, and the value of the
338 .Ev LANG
339 environment variable is not set, the locale for that specific
340 category defaults to the C locale.
341 The C or POSIX locale assumes the 7-bit ASCII character set and defines
342 information for the six categories.
343 .El
344 .Ss Character Sets
345 A character is any symbol used for the organization, control, or
346 representation of data.
347 A group of such symbols used to describe a
348 particular language make up a character set.
349 It is the encoding values in a character set that provide
350 the interface between the system and its input and output devices.
351 .Pp
352 The following character sets are supported in
353 .Dx
354 .Bl -tag -width ISO8859_family
355 .It ISO8859 family
356 Industry-standard character sets are provided by means of the ISO8859
357 family of character sets, which provide a range of single-byte character set
358 support that includes Latin-1, Latin-2, Arabic, Cyrillic, Hebrew,
359 Greek, and Turkish.
360 The eucJP character set is the industry-standard character set used to support
361 the Japanese locale.
362 .It Unicode
363 A Unicode environment based on the UTF-8 character set is supported for all
364 supported language/territories.
365 UTF-8 provides character support for most of the major languages of the
366 world and can be used in environments where multiple languages must be
367 processed simultaneously.
368 .El
369 .Ss Font Sets
370 A font set contains the glyphs to be displayed on the screen for a
371 corresponding character in a character set.
372 A display must support a suitable font to display a character set.
373 If suitable fonts are available to the X server, then X clients can
374 include support for different character sets.
375 .Xr xterm 1
376 includes support for UTF-8 character sets.
377 .Xr xfd 1
378 is useful for displaying all the characters in an X font.
379 .Pp
380 The
381 .Dx
382 .Xr syscons 4
383 console provides support for loading a variety of fonts using the
384 .Xr vidcontrol 1
385 utility. Available fonts can be found in
386 .Pa /usr/share/syscons/fonts .
387 .Ss Internationalization for Programmers
388 To facilitate translations of messages into various languages and to
389 make the translated messages available to the program based on a
390 user's locale, it is necessary to keep messages separate from the
391 programs and provide them in the form of message catalogs that a
392 program can access at run time.
393 .Pp
394 Access to locale information is provided through the
395 .Xr setlocale 3
396 and
397 .Xr nl_langinfo 3
398 interfaces.
399 See their respective man pages for further information.
400 .Pp
401 Message source files containing application messages are created by
402 the programmer and converted to message catalogs.
403 These catalogs are used by the application to retrieve and display
404 messages, as needed.
405 .Pp
406 .Dx
407 supports two message catalog interfaces: the X/Open
408 .Xr catgets 3
409 interface and the Uniforum
410 .Xr gettext 3
411 interface.
412 The
413 .Xr catgets 3
414 interface has the advantage that it belongs to a standard which is
415 well supported.
416 Unfortunately the interface is complicated to use and
417 maintenance of the catalogs is difficult.
418 The implementation also doesn't support different character sets.
419 The
420 .Xr gettext 3
421 interface has not been standardized yet, however it is being supported
422 by an increasing number of systems.
423 It also provides many additional tools which make programming and
424 catalog maintenance much easier.
425 .Ss Support for Multibyte Characters and Wide Characters
426 Character sets with multibyte characters may be difficult to decode, or may
427 contain state (i.e., adjacent characters are dependent).
428 ISO C specifies a set of functions using 'wide characters' which can handle
429 multibyte characters properly.
430 A wide character is specified in ISO C
431 as being a fixed number of bits wide and is stateless.
432 .Pp
433 There are two types for wide characters:
434 .Em wchar_t
435 and
436 .Em wint_t .
437 .Em wchar_t
438 is a type which can contain one wide character and operates like 'char'
439 type does for one character.
440 .Em wint_t
441 can contain one wide character or WEOF (wide EOF).
442 .Pp
443 There are functions that operate on
444 .Em wchar_t ,
445 and substitute for functions operating on 'char'.
446 See
447 .Xr wmemchr 3
448 and
449 .Xr towlower 3
450 for details.
451 There are some additional functions that operate on
452 .Em wchar_t .
453 See
454 .Xr wctype 3
455 and
456 .Xr wctrans 3
457 for details.
458 .Pp
459 Wide characters should be used for all I/O processing which may rely
460 on locale-specific strings.
461 The two primary issues requiring special use of wide characters are:
462 .Bl -bullet -offset indent
463 .It
464 All I/O is performed using multibyte characters.
465 Input data is converted into wide characters immediately after
466 reading and data for output is converted from wide characters to
467 multibyte characters immediately before writing.
468 Conversion is achieved using
469 .Xr mbstowcs 3 ,
470 .Xr mbsrtowcs 3 ,
471 .Xr wcstombs 3 ,
472 .Xr wcsrtombs 3 ,
473 .Xr mblen 3 ,
474 .Xr mbrlen 3 ,
475 and
476 .Xr  mbsinit 3 .
477 .It
478 Wide characters are used directly for I/O, using
479 .Xr getwchar 3 ,
480 .Xr fgetwc 3 ,
481 .Xr getwc 3 ,
482 .Xr ungetwc 3 ,
483 .Xr fgetws 3 ,
484 .Xr putwchar 3 ,
485 .Xr fputwc 3 ,
486 .Xr putwc 3 ,
487 and
488 .Xr fputws 3 .
489 They are also used for formatted I/O functions for wide characters
490 such as
491 .Xr fwscanf 3 ,
492 .Xr wscanf 3 ,
493 .Xr swscanf 3 ,
494 .Xr fwprintf 3 ,
495 .Xr wprintf 3 ,
496 .Xr swprintf 3 ,
497 .Xr vfwprintf 3 ,
498 .Xr vwprintf 3 ,
499 and
500 .Xr vswprintf 3 ,
501 and wide character identifier of %lc, %C, %ls, %S for conventional
502 formatted I/O functions.
503 .El
504 .Sh SEE ALSO
505 .Xr gencat 1 ,
506 .Xr vidcontrol 1 ,
507 .Xr xfd 1 ,
508 .Xr xterm 1 ,
509 .Xr catgets 3 ,
510 .Xr gettext 3 ,
511 .Xr nl_langinfo 3 ,
512 .Xr setlocale 3
513 .Sh BUGS
514 This man page is incomplete.