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