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