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 77and 78.Xr multibyte 3 79functions. 80This controls recognition of upper and lower case, 81alphabetic or non-alphabetic characters, 82and so on. 83.It Dv LC_MESSAGES 84Set a locale for message catalogs, see 85.Xr catopen 3 86function. 87.It Dv LC_MONETARY 88Set a locale for formatting monetary values; 89this affects the 90.Fn localeconv 91function. 92.It Dv LC_NUMERIC 93Set a locale for formatting numbers. 94This controls the formatting of decimal points 95in input and output of floating point numbers 96in functions such as 97.Fn printf 98and 99.Fn scanf , 100as well as values returned by 101.Fn localeconv . 102.It Dv LC_TIME 103Set a locale for formatting dates and times using the 104.Fn strftime 105function. 106.El 107.Pp 108Only three locales are defined by default, 109the empty string 110.Li "\&""\|"" 111which denotes the native environment, and the 112.Li "\&""C"" 113and 114.Li "\&""POSIX"" 115locales, which denote the C language environment. 116A 117.Fa locale 118argument of 119.Dv NULL 120causes 121.Fn setlocale 122to return the current locale. 123By default, C programs start in the 124.Li "\&""C"" 125locale. 126The only function in the library that sets the locale is 127.Fn setlocale ; 128the locale is never changed as a side effect of some other routine. 129.Sh RETURN VALUES 130Upon successful completion, 131.Fn setlocale 132returns the string associated with the specified 133.Fa category 134for the requested 135.Fa locale . 136The 137.Fn setlocale 138function returns 139.Dv NULL 140and fails to change the locale 141if the given combination of 142.Fa category 143and 144.Fa locale 145makes no sense. 146.Sh FILES 147.Bl -tag -width /usr/share/locale/locale/category -compact 148.It Pa $PATH_LOCALE/ Ns Em locale/category 149.It Pa /usr/share/locale/ Ns Em locale/category 150locale file for the locale 151.Em locale 152and the category 153.Em category . 154.El 155.Sh ERRORS 156No errors are defined. 157.Sh SEE ALSO 158.Xr colldef 1 , 159.Xr mklocale 1 , 160.Xr catopen 3 , 161.Xr ctype 3 , 162.Xr localeconv 3 , 163.Xr multibyte 3 , 164.Xr strcoll 3 , 165.Xr strxfrm 3 , 166.Xr euc 5 , 167.Xr utf8 5 , 168.Xr environ 7 169.Sh STANDARDS 170The 171.Fn setlocale 172function conforms to 173.St -isoC-99 . 174.Sh HISTORY 175The 176.Fn setlocale 177function first appeared in 178.Bx 4.4 . 179