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