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.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93 32.\" $FreeBSD$ 33.\" 34.Dd August 7, 2020 35.Dt SETLOCALE 3 36.Os 37.Sh NAME 38.Nm setlocale 39.Nd natural language formatting for C 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In locale.h 44.Ft char * 45.Fn setlocale "int category" "const char *locale" 46.Sh DESCRIPTION 47The 48.Fn setlocale 49function sets the C library's notion 50of natural language formatting style 51for particular sets of routines. 52Each such style is called a 53.Sq locale 54and is invoked using an appropriate name passed as a C string. 55.Pp 56The 57.Fn setlocale 58function recognizes several categories of routines. 59These are the categories and the sets of routines they select: 60.Bl -tag -width LC_MONETARY 61.It Dv LC_ALL 62Set the entire locale generically. 63.It Dv LC_COLLATE 64Set a locale for string collation routines. 65This controls alphabetic ordering in 66.Fn strcoll 67and 68.Fn strxfrm . 69.It Dv LC_CTYPE 70Set a locale for the 71.Xr ctype 3 72and 73.Xr multibyte 3 74functions. 75This controls recognition of upper and lower case, 76alphabetic or non-alphabetic characters, 77and so on. 78.It Dv LC_MESSAGES 79Set a locale for message catalogs, see 80.Xr catopen 3 81function. 82.It Dv LC_MONETARY 83Set a locale for formatting monetary values; 84this affects the 85.Fn localeconv 86function. 87.It Dv LC_NUMERIC 88Set a locale for formatting numbers. 89This controls the formatting of decimal points 90in input and output of floating point numbers 91in functions such as 92.Fn printf 93and 94.Fn scanf , 95as well as values returned by 96.Fn localeconv . 97.It Dv LC_TIME 98Set a locale for formatting dates and times using the 99.Fn strftime 100function. 101.It Dv LANG 102Sets the generic locale category for native language, local customs 103and coded character set in the absence of more specific locale 104variables. 105.El 106.Pp 107Only three locales are defined by default, 108the empty string 109.Li \&"\|" 110which denotes the native environment, and the 111.Li \&"C" 112and 113.Li \&"POSIX" 114locales, which denote the C language environment. 115A 116.Fa locale 117argument of 118.Dv NULL 119causes 120.Fn setlocale 121to return the current locale. 122.Pp 123The option 124.Fl a 125to the 126.Xr locale 1 127command can be used to display all further possible names for the 128.Fa locale 129argument that are recognized. 130Specifying any unrecognized value for 131.Fa locale 132makes 133.Fn setlocale 134fail. 135.Pp 136By default, C programs start in the 137.Li \&"C" 138locale. 139.Pp 140The only function in the library that sets the locale is 141.Fn setlocale ; 142the locale is never changed as a side effect of some other routine. 143.Sh RETURN VALUES 144Upon successful completion, 145.Fn setlocale 146returns the string associated with the specified 147.Fa category 148for the requested 149.Fa locale . 150The 151.Fn setlocale 152function returns 153.Dv NULL 154and fails to change the locale 155if the given combination of 156.Fa category 157and 158.Fa locale 159makes no sense. 160.Sh FILES 161.Bl -tag -width /usr/share/locale/locale/category -compact 162.It Pa $PATH_LOCALE/ Ns Em locale/category 163.It Pa /usr/share/locale/ Ns Em locale/category 164locale file for the locale 165.Em locale 166and the category 167.Em category . 168.El 169.Sh EXAMPLES 170The following code illustrates how a program can initialize the 171international environment for one language, while selectively 172modifying the program's locale such that regular expressions and 173string operations can be applied to text recorded in a different 174language: 175.Bd -literal 176 setlocale(LC_ALL, "de"); 177 setlocale(LC_COLLATE, "fr"); 178.Ed 179.Pp 180When a process is started, its current locale is set to the C or POSIX 181locale. 182An internationalized program that depends on locale data not defined in 183the C or POSIX locale must invoke the setlocale subroutine in the 184following manner before using any of the locale-specific information: 185.Bd -literal 186 setlocale(LC_ALL, ""); 187.Ed 188.Sh ERRORS 189No errors are defined. 190.Sh SEE ALSO 191.Xr locale 1 , 192.Xr localedef 1 , 193.Xr catopen 3 , 194.Xr ctype 3 , 195.Xr localeconv 3 , 196.Xr multibyte 3 , 197.Xr strcoll 3 , 198.Xr strxfrm 3 , 199.Xr euc 5 , 200.Xr utf8 5 , 201.Xr environ 7 202.Sh STANDARDS 203The 204.Fn setlocale 205function conforms to 206.St -isoC-99 . 207.Sh HISTORY 208The 209.Fn setlocale 210function first appeared in 211.Bx 4.4 . 212