1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Donn Seeley at BSDI. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd August 7, 2020 32.Dt SETLOCALE 3 33.Os 34.Sh NAME 35.Nm setlocale 36.Nd natural language formatting for C 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In locale.h 41.Ft char * 42.Fn setlocale "int category" "const char *locale" 43.Sh DESCRIPTION 44The 45.Fn setlocale 46function sets the C library's notion 47of natural language formatting style 48for particular sets of routines. 49Each such style is called a 50.Sq locale 51and is invoked using an appropriate name passed as a C string. 52.Pp 53The 54.Fn setlocale 55function recognizes several categories of routines. 56These are the categories and the sets of routines they select: 57.Bl -tag -width LC_MONETARY 58.It Dv LC_ALL 59Set the entire locale generically. 60.It Dv LC_COLLATE 61Set a locale for string collation routines. 62This controls alphabetic ordering in 63.Fn strcoll 64and 65.Fn strxfrm . 66.It Dv LC_CTYPE 67Set a locale for the 68.Xr ctype 3 69and 70.Xr multibyte 3 71functions. 72This controls recognition of upper and lower case, 73alphabetic or non-alphabetic characters, 74and so on. 75.It Dv LC_MESSAGES 76Set a locale for message catalogs, see 77.Xr catopen 3 78function. 79.It Dv LC_MONETARY 80Set a locale for formatting monetary values; 81this affects the 82.Fn localeconv 83function. 84.It Dv LC_NUMERIC 85Set a locale for formatting numbers. 86This controls the formatting of decimal points 87in input and output of floating point numbers 88in functions such as 89.Fn printf 90and 91.Fn scanf , 92as well as values returned by 93.Fn localeconv . 94.It Dv LC_TIME 95Set a locale for formatting dates and times using the 96.Fn strftime 97function. 98.It Dv LANG 99Sets the generic locale category for native language, local customs 100and coded character set in the absence of more specific locale 101variables. 102.El 103.Pp 104Only three locales are defined by default, 105the empty string 106.Li \&"\|" 107which denotes the native environment, and the 108.Li \&"C" 109and 110.Li \&"POSIX" 111locales, which denote the C language environment. 112A 113.Fa locale 114argument of 115.Dv NULL 116causes 117.Fn setlocale 118to return the current locale. 119.Pp 120The option 121.Fl a 122to the 123.Xr locale 1 124command can be used to display all further possible names for the 125.Fa locale 126argument that are recognized. 127Specifying any unrecognized value for 128.Fa locale 129makes 130.Fn setlocale 131fail. 132.Pp 133By default, C programs start in the 134.Li \&"C" 135locale. 136.Pp 137The only function in the library that sets the locale is 138.Fn setlocale ; 139the locale is never changed as a side effect of some other routine. 140.Sh RETURN VALUES 141Upon successful completion, 142.Fn setlocale 143returns the string associated with the specified 144.Fa category 145for the requested 146.Fa locale . 147The 148.Fn setlocale 149function returns 150.Dv NULL 151and fails to change the locale 152if the given combination of 153.Fa category 154and 155.Fa locale 156makes no sense. 157.Sh FILES 158.Bl -tag -width /usr/share/locale/locale/category -compact 159.It Pa $PATH_LOCALE/ Ns Em locale/category 160.It Pa /usr/share/locale/ Ns Em locale/category 161locale file for the locale 162.Em locale 163and the category 164.Em category . 165.El 166.Sh EXAMPLES 167The following code illustrates how a program can initialize the 168international environment for one language, while selectively 169modifying the program's locale such that regular expressions and 170string operations can be applied to text recorded in a different 171language: 172.Bd -literal 173 setlocale(LC_ALL, "de"); 174 setlocale(LC_COLLATE, "fr"); 175.Ed 176.Pp 177When a process is started, its current locale is set to the C or POSIX 178locale. 179An internationalized program that depends on locale data not defined in 180the C or POSIX locale must invoke the setlocale subroutine in the 181following manner before using any of the locale-specific information: 182.Bd -literal 183 setlocale(LC_ALL, ""); 184.Ed 185.Sh ERRORS 186No errors are defined. 187.Sh SEE ALSO 188.Xr locale 1 , 189.Xr localedef 1 , 190.Xr catopen 3 , 191.Xr ctype 3 , 192.Xr localeconv 3 , 193.Xr multibyte 3 , 194.Xr strcoll 3 , 195.Xr strxfrm 3 , 196.Xr euc 5 , 197.Xr utf8 5 , 198.Xr environ 7 199.Sh STANDARDS 200The 201.Fn setlocale 202function conforms to 203.St -isoC-99 . 204.Sh HISTORY 205The 206.Fn setlocale 207function first appeared in 208.Bx 4.4 . 209