1.\" $OpenBSD: newlocale.3,v 1.3 2019/06/25 17:40:24 schwarze Exp $ 2.\" 3.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: June 25 2019 $ 18.Dt NEWLOCALE 3 19.Os 20.Sh NAME 21.Nm newlocale , 22.Nm duplocale , 23.Nm freelocale 24.Nd create and destroy locale objects 25.Sh SYNOPSIS 26.In locale.h 27.Ft locale_t 28.Fo newlocale 29.Fa "int mask" 30.Fa "const char *locname" 31.Fa "locale_t oldloc" 32.Fc 33.Ft locale_t 34.Fo duplocale 35.Fa "locale_t oldloc" 36.Fc 37.Ft void 38.Fo freelocale 39.Fa "locale_t oldloc" 40.Fc 41.Sh DESCRIPTION 42The function 43.Fn newlocale 44creates a new locale object for use with 45.Xr uselocale 3 46and with many functions that accept 47.Vt locale_t 48arguments. 49Locale categories not contained in the 50.Fa mask 51are copied from 52.Fa oldloc 53to the new locale object, or from the 54.Qq C 55locale if 56.Fa oldloc 57is 58.Po Vt locale_t Pc Ns 0 . 59.Pp 60On 61.Ox , 62.Fa locname 63only affects the return value if 64.Fa mask 65includes 66.Dv LC_CTYPE_MASK , 67and 68.Fa locname 69is only meaningful if it is 70.Qq C 71or 72.Qq POSIX , 73if it ends with 74.Qq .UTF-8 , 75or if it is an empty string. 76Other 77.Fa locname 78arguments have the same effect as 79.Qq C . 80.Pp 81The function 82.Fn duplocale 83copies 84.Fa oldloc , 85or the global locale if given the special argument 86.Dv LC_GLOBAL_LOCALE . 87.Pp 88For portability, when an object returned from 89.Fn newlocale 90or 91.Fn duplocale 92is no longer needed, pass it to 93.Fn freelocale , 94even though the latter has no effect on 95.Ox . 96The 97.Fa oldloc 98objects passed to 99.Fn newlocale 100or 101.Fn freelocale 102become invalid, and using them or passing them once again to 103.Fn freelocale 104results in undefined behaviour, whereas objects passed to 105.Fn duplocale 106remain valid and can be passed to 107.Fn freelocale 108later on. 109.Sh RETURN VALUES 110The functions 111.Fn newlocale 112and 113.Fn duplocale 114return the new locale object on success or 115.Po Vt locale_t Pc Ns 0 116on failure. 117.Sh ENVIRONMENT 118If 119.Fa locname 120is an empty string, 121.Fa newlocale 122inspects 123.Ev LC_ALL , 124.Ev LC_CTYPE , 125and 126.Ev LANG 127as described in 128.Xr locale 1 . 129.Sh ERRORS 130The function 131.Fn newlocale 132fails if: 133.Bl -tag -width Er 134.It Bq Er EINVAL 135An invalid bit is set in 136.Fa mask , 137or 138.Fa locname 139is 140.Dv NULL . 141.It Bq Er ENOENT 142Locale data is not available for 143.Fa locname . 144.El 145.Pp 146On other operating systems, 147.Fn newlocale 148and 149.Fn duplocale 150may also fail with 151.Er ENOMEM . 152.Sh SEE ALSO 153.Xr iswalnum 3 , 154.Xr iswctype 3 , 155.Xr towctrans 3 , 156.Xr towlower 3 , 157.Xr uselocale 3 , 158.Xr wcscasecmp 3 , 159.Xr wctrans 3 , 160.Xr wctype 3 161.Sh STANDARDS 162These functions conform to 163.St -p1003.1-2008 164including Technical Corrigendum 3. 165.Sh HISTORY 166These functions have been available since 167.Ox 6.2 . 168.Sh CAVEATS 169Calling 170.Fn newlocale 171with an 172.Fa oldloc 173argument of 174.Dv LC_GLOBAL_LOCALE 175results in undefined behaviour. 176