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 September 9, 2019 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.El 102.Pp 103Only three locales are defined by default, 104the empty string 105.Li \&"\|" 106which denotes the native environment, and the 107.Li \&"C" 108and 109.Li \&"POSIX" 110locales, which denote the C language environment. 111A 112.Fa locale 113argument of 114.Dv NULL 115causes 116.Fn setlocale 117to return the current locale. 118.Pp 119The option 120.Fl a 121to the 122.Xr locale 1 123command can be used to display all further possible names for the 124.Fa locale 125argument that are recognized. 126Specifying any unrecognized value for 127.Fa locale 128makes 129.Fn setlocale 130fail. 131.Pp 132By default, C programs start in the 133.Li \&"C" 134locale. 135.Pp 136The only function in the library that sets the locale is 137.Fn setlocale ; 138the locale is never changed as a side effect of some other routine. 139.Sh RETURN VALUES 140Upon successful completion, 141.Fn setlocale 142returns the string associated with the specified 143.Fa category 144for the requested 145.Fa locale . 146The 147.Fn setlocale 148function returns 149.Dv NULL 150and fails to change the locale 151if the given combination of 152.Fa category 153and 154.Fa locale 155makes no sense. 156.Sh FILES 157.Bl -tag -width /usr/share/locale/locale/category -compact 158.It Pa $PATH_LOCALE/ Ns Em locale/category 159.It Pa /usr/share/locale/ Ns Em locale/category 160locale file for the locale 161.Em locale 162and the category 163.Em category . 164.El 165.Sh ERRORS 166No errors are defined. 167.Sh SEE ALSO 168.Xr locale 1 , 169.Xr localedef 1 , 170.Xr catopen 3 , 171.Xr ctype 3 , 172.Xr localeconv 3 , 173.Xr multibyte 3 , 174.Xr strcoll 3 , 175.Xr strxfrm 3 , 176.Xr euc 5 , 177.Xr utf8 5 , 178.Xr environ 7 179.Sh STANDARDS 180The 181.Fn setlocale 182function conforms to 183.St -isoC-99 . 184.Sh HISTORY 185The 186.Fn setlocale 187function first appeared in 188.Bx 4.4 . 189