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.\" 4. 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 November 21, 2003 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.Pp 61.Bl -tag -width LC_MONETARY 62.It Dv LC_ALL 63Set the entire locale generically. 64.It Dv LC_COLLATE 65Set a locale for string collation routines. 66This controls alphabetic ordering in 67.Fn strcoll 68and 69.Fn strxfrm . 70.It Dv LC_CTYPE 71Set a locale for the 72.Xr ctype 3 73and 74.Xr multibyte 3 75functions. 76This controls recognition of upper and lower case, 77alphabetic or non-alphabetic characters, 78and so on. 79.It Dv LC_MESSAGES 80Set a locale for message catalogs, see 81.Xr catopen 3 82function. 83.It Dv LC_MONETARY 84Set a locale for formatting monetary values; 85this affects the 86.Fn localeconv 87function. 88.It Dv LC_NUMERIC 89Set a locale for formatting numbers. 90This controls the formatting of decimal points 91in input and output of floating point numbers 92in functions such as 93.Fn printf 94and 95.Fn scanf , 96as well as values returned by 97.Fn localeconv . 98.It Dv LC_TIME 99Set a locale for formatting dates and times using the 100.Fn strftime 101function. 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. 119By default, C programs start in the 120.Li "\&""C"" 121locale. 122The only function in the library that sets the locale is 123.Fn setlocale ; 124the locale is never changed as a side effect of some other routine. 125.Sh RETURN VALUES 126Upon successful completion, 127.Fn setlocale 128returns the string associated with the specified 129.Fa category 130for the requested 131.Fa locale . 132The 133.Fn setlocale 134function returns 135.Dv NULL 136and fails to change the locale 137if the given combination of 138.Fa category 139and 140.Fa locale 141makes no sense. 142.Sh FILES 143.Bl -tag -width /usr/share/locale/locale/category -compact 144.It Pa $PATH_LOCALE/ Ns Em locale/category 145.It Pa /usr/share/locale/ Ns Em locale/category 146locale file for the locale 147.Em locale 148and the category 149.Em category . 150.El 151.Sh ERRORS 152No errors are defined. 153.Sh SEE ALSO 154.Xr colldef 1 , 155.Xr mklocale 1 , 156.Xr catopen 3 , 157.Xr ctype 3 , 158.Xr localeconv 3 , 159.Xr multibyte 3 , 160.Xr strcoll 3 , 161.Xr strxfrm 3 , 162.Xr euc 5 , 163.Xr utf8 5 , 164.Xr environ 7 165.Sh STANDARDS 166The 167.Fn setlocale 168function conforms to 169.St -isoC-99 . 170.Sh HISTORY 171The 172.Fn setlocale 173function first appeared in 174.Bx 4.4 . 175