1.\" Copyright (c) 2011 The FreeBSD Foundation 2.\" 3.\" This documentation was written by David Chisnall under sponsorship from 4.\" the FreeBSD Foundation. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.Dd October 2, 2020 29.Dt NEWLOCALE 3 30.Os 31.Sh NAME 32.Nm newlocale 33.Nd Creates a new locale 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In locale.h 38.Ft locale_t 39.Fn newlocale "int mask" "const char * locale" "locale_t base" 40.Sh DESCRIPTION 41Creates a new locale, inheriting some properties from an existing locale. 42The 43.Fa mask 44defines the components that the new locale will have set to the locale with the 45name specified in the 46.Fa locale 47parameter. 48Any components not specified in 49.Fa mask 50will be inherited from the locale referenced by 51.Fa base , 52if 53.Fa base 54is not 55.Dv NULL . 56If the call is successful, the state of the locale referenced by 57.Fa base 58is unspecified, and it must not be accessed. 59The special locale 60.Dv LC_GLOBAL_LOCALE 61may not be specified for 62.Fa base . 63The 64.Fa mask 65is either 66.Fa LC_ALL_MASK , 67indicating all possible locale components, 68or the logical OR of some combination of the following: 69.Bl -tag -width "LC_MESSAGES_MASK" -offset indent 70.It LC_COLLATE_MASK 71The locale for string collation routines. 72This controls alphabetic ordering in 73.Xr strcoll 3 74and 75.Xr strxfrm 3 . 76.It LC_CTYPE_MASK 77The locale for the 78.Xr ctype 3 79and 80.Xr multibyte 3 81functions. 82This controls recognition of upper and lower case, alphabetic or 83non-alphabetic characters, and so on. 84.It LC_MESSAGES_MASK 85Set a locale for message catalogs, see 86.Xr catopen 3 87function. 88.It LC_MONETARY_MASK 89Set a locale for formatting monetary values; this affects 90the 91.Xr localeconv 3 92function. 93.It LC_NUMERIC_MASK 94Set a locale for formatting numbers. 95This controls the formatting of decimal points in input and output of floating 96point numbers in functions such as 97.Xr printf 3 98and 99.Xr scanf 3 , 100as well as values returned by 101.Xr localeconv 3 . 102.It LC_TIME_MASK 103Set a locale for formatting dates and times using the 104.Xr strftime 3 105function. 106.El 107This function uses the same rules for loading locale components as 108.Xr setlocale 3 . 109.Sh RETURN VALUES 110Returns a new, valid, 111.Fa locale_t 112or NULL if an error occurs. 113You must free the returned locale with 114.Xr freelocale 3 . 115.Sh SEE ALSO 116.Xr duplocale 3 , 117.Xr freelocale 3 , 118.Xr localeconv 3 , 119.Xr querylocale 3 , 120.Xr uselocale 3 , 121.Xr xlocale 3 122.Sh STANDARDS 123This function conforms to 124.St -p1003.1-2008 . 125