1.\" $OpenBSD: setlocale.3,v 1.24 2022/08/04 06:20:24 jsg Exp $ 2.\" $NetBSD: setlocale.3,v 1.3 1997/07/14 23:19:47 kleink Exp $ 3.\" 4.\" Copyright (c) 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Donn Seeley at BSDI. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93 35.\" 36.Dd $Mdocdate: August 4 2022 $ 37.Dt SETLOCALE 3 38.Os 39.Sh NAME 40.Nm setlocale 41.Nd select character encoding 42.Sh SYNOPSIS 43.In locale.h 44.Ft char * 45.Fn setlocale "int category" "const char *locale" 46.Sh DESCRIPTION 47The 48.Fn setlocale 49function sets and retrieves the active 50.Fa locale 51for the current process. 52The locale modifies the behaviour of some functions in the C library 53with respect to the character encoding, and on other operating systems 54also with respect to some language and cultural conventions. 55For more information about locales in general, see the 56.Xr locale 1 57manual page. 58.Pp 59On 60.Ox , 61the only useful value for the 62.Fa category 63is 64.Dv LC_CTYPE . 65It sets the locale used for character encoding, character classification, 66and case conversion. 67For compatibility with natural language support in 68.Xr packages 7 , 69all other categories \(em 70.Dv LC_COLLATE , 71.Dv LC_MESSAGES , 72.Dv LC_MONETARY , 73.Dv LC_NUMERIC , 74and 75.Dv LC_TIME 76\(em can be set and retrieved, too, but their values are ignored by the 77.Ox 78C library. 79A category of 80.Dv LC_ALL 81sets the entire locale generically, which is strongly discouraged for 82security reasons in portable programs. 83.Pp 84The syntax and semantics of the 85.Fa locale 86argument are not standardized and vary among operating systems. 87On 88.Ox , 89if the 90.Fa locale 91string ends with 92.Qq ".UTF-8" , 93the UTF-8 locale is selected; otherwise, the 94.Qq C 95locale is selected, which uses the ASCII character set. 96If the 97.Fa locale 98contains a dot but does not end with 99.Qq ".UTF-8" , 100.Fn setlocale 101fails. 102.Pp 103If 104.Fa locale 105is an empty string 106.Pq Qq , 107the value of the environment variable 108.Ev LC_ALL , 109with a fallback to the variable corresponding to 110.Fa category , 111and with a further fallback to 112.Ev LANG , 113is used instead, as documented in the 114.Xr locale 1 115manual page. 116.Pp 117If 118.Fa locale 119is 120.Dv NULL , 121the locale remains unchanged. 122This can be used to determine the currently active locale. 123.Pp 124By default, C programs start in the 125.Qq C 126locale. 127The only function in the library that sets the locale is 128.Fn setlocale ; 129the locale is never changed as a side effect of some other routine. 130.Pp 131The 132.Dv LC_CTYPE 133category modifies the behaviour of at least the following functions: 134.Xr iswctype 3 , 135.Xr mblen 3 , 136.Xr mbrlen 3 , 137.Xr mbrtowc 3 , 138.Xr mbsrtowcs 3 , 139.Xr mbstowcs 3 , 140.Xr mbtowc 3 , 141.Xr towctrans 3 , 142.Xr towlower 3 , 143.Xr towupper 3 , 144.Xr wcrtomb 3 , 145.Xr wcscasecmp 3 , 146.Xr wcsrtombs 3 , 147.Xr wcstombs 3 , 148.Xr wctomb 3 , 149.Xr wctrans 3 , 150.Xr wctype 3 , 151and the functions documented in 152.Xr iswalnum 3 . 153.Sh RETURN VALUES 154In case of success, 155.Fn setlocale 156returns a pointer to a static string describing the locale 157that is in force after the call. 158Subsequent calls to 159.Fn setlocale 160may change the content of the string. 161The format of the string is not standardized and varies among 162operating systems. 163.Pp 164On 165.Ox , 166if 167.Fn setlocale 168was never called with a 169.Pf non- Dv NULL 170.Fa locale 171argument, the string 172.Qq C 173is returned. 174Otherwise, if the 175.Fa category 176was not 177.Dv LC_ALL 178or if the locale is the same for all categories, a copy of the 179.Fa locale 180argument is returned. 181Otherwise, the locales for the six categories 182.Dv LC_COLLATE , 183.Dv LC_CTYPE , 184.Dv LC_MESSAGES , 185.Dv LC_MONETARY , 186.Dv LC_NUMERIC , 187.Dv LC_TIME 188are concatenated in that order, with slash 189.Pq Ql / 190characters in between. 191.Pp 192In case of failure, 193.Fn setlocale 194returns 195.Dv NULL . 196On 197.Ox , 198that can only happen if the 199.Fa category 200is invalid, if a character encoding other than UTF-8 is requested, 201if the requested 202.Fa locale 203name is of excessive length, or if memory allocation fails. 204.Sh EXAMPLES 205Calling 206.Pp 207.Dl setlocale(LC_CTYPE, \(dqen_US.UTF-8\(dq); 208.Pp 209at the beginning of a program selects the UTF-8 locale and returns 210.Qq en_US.UTF-8 . 211Calling 212.Pp 213.Dl setlocale(LC_ALL, NULL); 214.Pp 215right afterwards leaves the locale unchanged and returns 216.Qq C/en_US.UTF-8/C/C/C/C . 217.Sh SEE ALSO 218.Xr locale 1 , 219.Xr newlocale 3 , 220.Xr nl_langinfo 3 , 221.Xr uselocale 3 222.Sh STANDARDS 223The 224.Fn setlocale 225function conforms to 226.St -ansiC . 227.Sh HISTORY 228The 229.Fn setlocale 230function first appeared in 231.Bx 4.3 Net/2 . 232.Sh CAVEATS 233On systems other than 234.Ox , 235calling 236.Fn setlocale 237or 238.Xr uselocale 3 239with a 240.Fa category 241other than 242.Dv LC_CTYPE 243can cause erratic behaviour of many library functions. 244For security reasons, make sure that portable programs only use 245.Dv LC_CTYPE . 246.Pp 247For example, the following functions may be affected. 248The list is probably incomplete. 249For example, additional library functions may be impacted 250if they directly or indirectly call affected functions, 251or if they attempt to imitate aspects of their behaviour. 252Functions that are not standardized may be affected too. 253.Bl -tag -width Ds 254.It Dv LC_COLLATE 255.Xr glob 3 , 256.Xr strcoll 3 , 257.Xr strxfrm 3 , 258.Xr wcscoll 3 , 259.Xr wcsxfrm 3 , 260and the functions documented in 261.Xr regexec 3 262.It Dv LC_MESSAGES 263.Xr catgets 3 , 264.Xr catopen 3 , 265.Xr nl_langinfo 3 , 266.Xr perror 3 , 267.Xr psignal 3 , 268.Xr strerror 3 , 269.Xr strsignal 3 , 270and the functions documented in 271.Xr err 3 272.It Dv LC_MONETARY 273.Xr localeconv 3 , 274.Xr nl_langinfo 3 , 275.Fn strfmon 276.It Dv LC_NUMERIC 277.Xr atof 3 , 278.Xr localeconv 3 , 279.Xr nl_langinfo 3 , 280.Fn strfmon , 281and the functions documented in 282.Xr printf 3 , 283.Xr scanf 3 , 284.Xr strtod 3 , 285.Xr wcstod 3 , 286.Xr wprintf 3 , 287.Xr wscanf 3 . 288This category is particularly dangerous because it can cause bugs 289in the parsing and formatting of numbers, for example failures to 290recognize or properly write decimal points. 291.It Dv LC_TIME 292.Fn getdate , 293.Xr nl_langinfo 3 , 294.Xr strftime 3 , 295.Xr strptime 3 . 296Similarly, this is prone to causing bugs in the parsing and formatting 297of date strings. 298.It Dv LC_CTYPE 299On systems other than 300.Ox , 301this category may affect the behaviour of additional functions, 302for example: 303.Xr btowc 3 , 304.Xr isalnum 3 , 305.Xr isalpha 3 , 306.Xr isblank 3 , 307.Xr iscntrl 3 , 308.Xr isdigit 3 , 309.Xr isgraph 3 , 310.Xr islower 3 , 311.Xr isprint 3 , 312.Xr ispunct 3 , 313.Xr isspace 3 , 314.Xr isupper 3 , 315.Xr isxdigit 3 , 316.Xr mbsinit 3 , 317.Xr strcasecmp 3 , 318.Xr strcoll 3 , 319.Xr strxfrm 3 , 320.Xr tolower 3 , 321.Xr toupper 3 , 322.Xr vis 3 , 323.Xr wcscoll 3 , 324.Xr wcsxfrm 3 , 325.Xr wctob 3 326.El 327