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. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93 36.\" $FreeBSD$ 37.\" 38.Dd November 21, 2003 39.Dt SETLOCALE 3 40.Os 41.Sh NAME 42.Nm setlocale 43.Nd natural language formatting for C 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In locale.h 48.Ft char * 49.Fn setlocale "int category" "const char *locale" 50.Sh DESCRIPTION 51The 52.Fn setlocale 53function sets the C library's notion 54of natural language formatting style 55for particular sets of routines. 56Each such style is called a 57.Sq locale 58and is invoked using an appropriate name passed as a C string. 59.Pp 60The 61.Fn setlocale 62function recognizes several categories of routines. 63These are the categories and the sets of routines they select: 64.Pp 65.Bl -tag -width LC_MONETARY 66.It Dv LC_ALL 67Set the entire locale generically. 68.It Dv LC_COLLATE 69Set a locale for string collation routines. 70This controls alphabetic ordering in 71.Fn strcoll 72and 73.Fn strxfrm . 74.It Dv LC_CTYPE 75Set a locale for the 76.Xr ctype 3 , 77.Xr mbrune 3 , 78.Xr multibyte 3 79and 80.Xr rune 3 81functions. 82This controls recognition of upper and lower case, 83alphabetic or non-alphabetic characters, 84and so on. 85The real work is done by the 86.Fn setrunelocale 87function. 88.It Dv LC_MESSAGES 89Set a locale for message catalogs, see 90.Xr catopen 3 91function. 92.It Dv LC_MONETARY 93Set a locale for formatting monetary values; 94this affects the 95.Fn localeconv 96function. 97.It Dv LC_NUMERIC 98Set a locale for formatting numbers. 99This controls the formatting of decimal points 100in input and output of floating point numbers 101in functions such as 102.Fn printf 103and 104.Fn scanf , 105as well as values returned by 106.Fn localeconv . 107.It Dv LC_TIME 108Set a locale for formatting dates and times using the 109.Fn strftime 110function. 111.El 112.Pp 113Only three locales are defined by default, 114the empty string 115.Li "\&""\|"" 116which denotes the native environment, and the 117.Li "\&""C"" 118and 119.Li "\&""POSIX"" 120locales, which denote the C language environment. 121A 122.Fa locale 123argument of 124.Dv NULL 125causes 126.Fn setlocale 127to return the current locale. 128By default, C programs start in the 129.Li "\&""C"" 130locale. 131The only function in the library that sets the locale is 132.Fn setlocale ; 133the locale is never changed as a side effect of some other routine. 134.Sh RETURN VALUES 135Upon successful completion, 136.Fn setlocale 137returns the string associated with the specified 138.Fa category 139for the requested 140.Fa locale . 141The 142.Fn setlocale 143function returns 144.Dv NULL 145and fails to change the locale 146if the given combination of 147.Fa category 148and 149.Fa locale 150makes no sense. 151.Sh ERRORS 152No errors are defined. 153.Sh FILES 154.Bl -tag -width /usr/share/locale/locale/category -compact 155.It Pa $PATH_LOCALE/ Ns Em locale/category 156.It Pa /usr/share/locale/ Ns Em locale/category 157locale file for the locale 158.Em locale 159and the category 160.Em category . 161.El 162.Sh SEE ALSO 163.Xr colldef 1 , 164.Xr mklocale 1 , 165.Xr catopen 3 , 166.Xr ctype 3 , 167.Xr localeconv 3 , 168.Xr mbrune 3 , 169.Xr multibyte 3 , 170.Xr rune 3 , 171.Xr strcoll 3 , 172.Xr strxfrm 3 , 173.Xr euc 5 , 174.Xr utf2 5 , 175.Xr utf8 5 , 176.Xr environ 7 177.Sh STANDARDS 178The 179.Fn setlocale 180function conforms to 181.St -isoC-99 . 182.Sh HISTORY 183The 184.Fn setlocale 185function first appeared in 186.Bx 4.4 . 187