Annotation of src/usr.bin/locale/locale.1, Revision 1.8
1.8 ! schwarze 1: .\" $OpenBSD: locale.1,v 1.7 2016/10/26 01:00:27 schwarze Exp $
1.1 stsp 2: .\"
1.8 ! schwarze 3: .\" Copyright 2016, 2020 Ingo Schwarze <schwarze@openbsd.org>
1.1 stsp 4: .\" Copyright 2013 Stefan Sperling <stsp@openbsd.org>
5: .\"
6: .\" Permission to use, copy, modify, and distribute this software for any
7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17: .\"
1.8 ! schwarze 18: .Dd $Mdocdate: October 26 2016 $
1.1 stsp 19: .Dt LOCALE 1
20: .Os
21: .Sh NAME
22: .Nm locale
1.6 schwarze 23: .Nd character encoding and localization conventions
1.1 stsp 24: .Sh SYNOPSIS
25: .Nm locale
1.8 ! schwarze 26: .Op Fl a | Fl m | Cm charmap
1.1 stsp 27: .Sh DESCRIPTION
1.6 schwarze 28: If the
1.1 stsp 29: .Nm
1.6 schwarze 30: utility is invoked without any arguments, the current locale
31: configuration is shown.
1.1 stsp 32: .Pp
33: The options are as follows:
1.8 ! schwarze 34: .Bl -tag -width charmap
1.1 stsp 35: .It Fl a
36: Display a list of supported locales.
37: .It Fl m
1.6 schwarze 38: Display a list of supported character encodings.
39: On
40: .Ox ,
41: this always returns UTF-8 only.
1.8 ! schwarze 42: .It Cm charmap
! 43: Display the currently selected character encoding.
! 44: On
! 45: .Ox ,
! 46: this returns either US-ASCII or UTF-8.
1.1 stsp 47: .El
1.6 schwarze 48: .Pp
1.7 schwarze 49: A locale is a set of environment variables telling programs which
50: character encoding, language and cultural conventions the user
51: prefers.
1.6 schwarze 52: Programs in the
53: .Ox
1.7 schwarze 54: base system ignore the locale except for the character encoding,
55: and it is not recommended to use any of these variables except that
56: the following non-default setting is supported as an option:
57: .Pp
58: .Dl export LC_CTYPE=en_US.UTF-8
59: .Pp
1.6 schwarze 60: Programs installed from
61: .Xr packages 7
62: may or may not change behavior according to the locale.
63: Many programs use the X/Open System Interfaces naming scheme
64: for the contents of the variables listed below, which is
65: .Sm off
66: .Ar language
67: .Op _ Ar TERRITORY
68: .Op \&. Ar encoding
69: .Op @ Ar modifier
70: .Sm on
71: .Pp
72: The behavior of some library functions may also depend on the locale,
73: and it does on most other operating systems.
74: The
75: .Ox
76: C library tends to avoid locale-dependent behavior except with
77: respect to character encoding.
78: See the manual pages of individual functions for details.
79: .Pp
80: The character encoding locale
81: .Ev LC_CTYPE
82: instructs programs which character encoding to assume for text input
83: and to use for text output.
84: A character encoding maps each character of a given character set
85: to a byte sequence suitable for storing or transmitting the character.
86: .Pp
87: The
88: .Ox
89: base system supports two locales: the default of
90: .Li LC_CTYPE=C
91: selects the US-ASCII character set and encoding, treating the bytes
92: 0x80 to 0xff as non-printable characters of application-specific
1.7 schwarze 93: meaning.
1.6 schwarze 94: .Li LC_CTYPE=POSIX
95: is an alias for
96: .Li LC_CTYPE=C .
1.7 schwarze 97: The alternative of
98: .Li LC_CTYPE=en_US.UTF-8
99: selects the UTF-8 encoding of the Unicode character set, which is
100: supported by many parts of the system, but not yet fully supported
101: by all parts.
1.6 schwarze 102: .Pp
103: If the value of
104: .Ev LC_CTYPE
105: ends in
106: .Ql .UTF-8 ,
107: programs in the
108: .Ox
109: base system ignore the beginning of it, treating for example zh_CN.UTF-8
110: exactly like en_US.UTF-8.
111: Programs from
112: .Xr packages 7
113: may however make a difference.
114: If the value of
115: .Ev LC_CTYPE
116: is unsupported, programs and libraries in the
117: .Ox
118: base systems fall back to
119: .Li LC_CTYPE=C .
120: .Pp
121: Some programs, for example
122: .Xr write 1 ,
123: deliberately ignore the locale and always use US-ASCII only.
124: See the manual pages of individual programs for details.
1.1 stsp 125: .Sh ENVIRONMENT
126: The locale configuration consists of the following environment variables:
1.6 schwarze 127: .Bl -tag -width LC_MONETARYX
128: .It Ev LC_ALL
129: Overrides all other
130: .Ev LC_*
131: variables below.
132: .It Ev LC_COLLATE
133: Intended to affect collation order.
134: It may for example affect alphabetic sorting, regular expressions
135: including equivalence classes, and the
136: .Xr strcoll 3
137: and
138: .Xr strxfrm 3
139: functions.
140: .It Ev LC_CTYPE
141: Intended to affect character encoding, character classification,
142: and case conversion.
143: For example, it is used by
144: .Xr mbtowc 3 ,
145: .Xr iswctype 3 ,
146: .Xr iswalnum 3 ,
147: .Xr towlower 3 ,
148: .Xr fgetwc 3 ,
149: .Xr fputwc 3 ,
150: .Xr printf 3 ,
151: and
152: .Xr scanf 3 .
153: .It Ev LC_MESSAGES
154: Intended to affect the output of informative and diagnostic messages
155: and the interpretation of interactive responses, in particular
156: regarding the language.
157: It is used by
158: .Xr catopen 3 .
159: .It Ev LC_MONETARY
160: Intended to affect monetary formatting.
161: .It Ev LC_NUMERIC
162: Intended to affect numeric, non-monetary formatting, for example
163: the radix character and thousands separators.
164: On other operating systems, it may for example affect
165: .Xr printf 3 ,
166: .Xr scanf 3 ,
167: and
168: .Xr strtod 3 .
169: .It Ev LC_TIME
170: Intended to affect date and time formats.
171: It may for example affect
172: .Xr strftime 3 .
173: .It Ev LANG
1.1 stsp 174: Fallback if any of the above is unset.
1.6 schwarze 175: .It Ev NLSPATH
176: Used by
177: .Xr catopen 3
178: to locate message catalogs.
179: .El
180: .Sh FILES
181: .Bl -tag -width Ds
182: .It Pa /usr/share/locale/UTF-8/LC_CTYPE
183: Character classification, case conversion, and character display
184: width database in
185: .Xr mklocale 1
186: binary output format used by
187: .Xr setlocale 3 .
188: .It Pa /usr/local/share/locale/
189: Localization data for
190: .Xr packages 7 ,
191: in particular
192: .Ev LC_MESSAGES
193: catalogs in GNU gettext format.
194: .It Pa /usr/local/share/nls/
195: Localization data for
196: .Xr packages 7 ,
197: in particular
198: .Ev LC_MESSAGES
199: catalogs in
200: .Xr catopen 3
201: format.
202: .It Pa /usr/src/share/locale/ctype/en_US.UTF-8.src
203: Character classification, case conversion, and character display
204: width database in
205: .Xr mklocale 1
206: input format.
207: .It Pa /usr/libdata/perl5/unicore/
208: Complete Unicode data used for generating the above database.
209: .It Pa /usr/src/gnu/usr.bin/perl/lib/unicore/UnicodeData.txt
210: The most important parts of Unicode data in a compact, more easily
211: human-readable format.
1.1 stsp 212: .El
1.4 jmc 213: .Sh EXIT STATUS
214: .Ex -std locale
1.1 stsp 215: .Sh SEE ALSO
1.6 schwarze 216: .Xr mklocale 1 ,
217: .Xr setlocale 3 ,
218: .Xr Unicode::UCD 3p
219: .Pp
220: Related ports: converters/libiconv, devel/gettext, textproc/icu4c
1.1 stsp 221: .Sh STANDARDS
1.6 schwarze 222: With respect to locale support, most libraries and programs in the
223: .Ox
224: base system, including the
1.1 stsp 225: .Nm
1.6 schwarze 226: utility, implement a subset of the
1.4 jmc 227: .St -p1003.1-2008
228: specification.
1.3 schwarze 229: .Sh HISTORY
230: The
231: .Nm
232: utility was first standardized in the
233: .St -xpg4 .
234: .Pp
235: It was rewritten from scratch for
236: .Ox 5.4
237: during the 2013 Toronto hackathon.
238: .Sh AUTHORS
1.4 jmc 239: .An -nosplit
1.3 schwarze 240: .An Stefan Sperling Aq Mt stsp@openbsd.org
241: with contributions from
242: .An Philip Guenther Aq Mt guenther@openbsd.org
243: and
244: .An Jeremie Courreges-Anglas Aq Mt jca@openbsd.org .
1.6 schwarze 245: This manual page was written by
246: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.1 stsp 247: .Sh BUGS
1.6 schwarze 248: The
249: .Nm
250: concept is inadequate for inter-process communication.
251: Two processes exchanging text, for example over a network, using
252: sockets, in shared memory, or even using plain text files always
253: need a protocol-specific way to negotiate the character encoding
254: used.
255: .Pp
1.1 stsp 256: The list of supported locales is perpetually incomplete.
![[BACK]](/icons/back.gif){kind=icon}
Return to locale.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / locale