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