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. 118By default, C programs start in the 119.Li \&"C" 120locale. 121The only function in the library that sets the locale is 122.Fn setlocale ; 123the locale is never changed as a side effect of some other routine. 124.Sh RETURN VALUES 125Upon successful completion, 126.Fn setlocale 127returns the string associated with the specified 128.Fa category 129for the requested 130.Fa locale . 131The 132.Fn setlocale 133function returns 134.Dv NULL 135and fails to change the locale 136if the given combination of 137.Fa category 138and 139.Fa locale 140makes no sense. 141.Sh FILES 142.Bl -tag -width /usr/share/locale/locale/category -compact 143.It Pa $PATH_LOCALE/ Ns Em locale/category 144.It Pa /usr/share/locale/ Ns Em locale/category 145locale file for the locale 146.Em locale 147and the category 148.Em category . 149.El 150.Sh ERRORS 151No errors are defined. 152.Sh SEE ALSO 153.Xr localedef 1 , 154.Xr catopen 3 , 155.Xr ctype 3 , 156.Xr localeconv 3 , 157.Xr multibyte 3 , 158.Xr strcoll 3 , 159.Xr strxfrm 3 , 160.Xr euc 5 , 161.Xr utf8 5 , 162.Xr environ 7 163.Sh STANDARDS 164The 165.Fn setlocale 166function conforms to 167.St -isoC-99 . 168.Sh HISTORY 169The 170.Fn setlocale 171function first appeared in 172.Bx 4.4 . 173