1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2025 Oxide Computer Company 13.\" 14.Dd April 11, 2025 15.Dt GETLOCALENAME_L 3C 16.Os 17.Sh NAME 18.Nm getlocalename_l 19.Nd get name of locale 20.Sh LIBRARY 21.Lb libc 22.Sh SYNOPSIS 23.In locale.h 24.Ft "const char *" 25.Fo getlocalename_l 26.Fa "int category" 27.Fa "locale_t locale" 28.Fc 29.Sh DESCRIPTION 30The 31.Fn getlocalename_l 32function returns the name of the specific 33.Fa category 34of the specified 35.Fa locale . 36If 37.Fa locale 38is 39.Dv LC_GLOBAL_LOCALE , 40then information will be returned about the current global locale. 41The global locale is changed by calls to 42.Xr setlocale 3C 43and not impacted by a thread calling 44.Xr uselocale 3C . 45.Pp 46When the category is 47.Dv LC_ALL , 48the returned string is a form that when passed to 49.Xr setlocale 3C 50it will result in the same locale being activated. 51Similarly, passing this locale to 52.Xr newlocale 3C 53will result in a comparable locale. 54Note, the latter is not strictly guaranteed by POSIX so portable applications 55may not want to rely on this behavior. 56.Pp 57The returned string's lifetime and the validity of the pointer is tied to the 58lifetime of the locale itself. 59This varies depending on whether this refers to the global locale or not. 60If it is not the global locale, calling either 61.Xr newlocale 3C 62or 63.Xr freelocale 3C 64on 65.Fa locale , 66means that the string is no longer valid. 67.Pp 68When querying the global locale, data lifetimes are more complicated. 69It is possible that calls to the 70.Fn getlocalename_l 71function may race with other threads calling 72.Xr setlocale 3C . 73The returned data will always be valid; however, depending on the interleaving 74of thread execution, the returned name may be from the prior locale during a 75contemporaneous 76.Xr setlocale 3C . 77This is the exception to the thread safety documented for this function. 78Portable applications should assume that data returned related to the global 79locale may be invalidated by the calling thread exiting or calling 80.Fn getlocalename_l 81again with 82.Dv LC_GLOBAL_LOCALE . 83.Sh RETURN VALUES 84Upon successful completion, the 85.Fn getlocalename_l 86returns the name of the 87.Fa category 88of 89.Fa locale . 90Otherwise, 91.Dv NULL 92is returned. 93.Sh EXAMPLES 94.Sy Example 1 95Printing the current thread's locale. 96.Pp 97This example queries the current thread's locale; however, it does not call 98.Xr freelocale 3C . 99Locales that are queried at run-time are still in use and therefore should not 100be freed. 101Instead, the logic that set the locale should free it after it changes the 102locale again. 103.Bd -literal 104#include <stdio.h> 105#include <locale.h> 106 107void 108print_locale(void) 109{ 110 locale_t loc = uselocale(NULL); 111 printf("%s\en", getlocalename_l(LC_ALL, LC_GLOBAL_LOCALE)); 112} 113.Ed 114.Pp 115.Sy Example 2 116Printing the global locale. 117.Bd -literal 118#include <stdio.h> 119#include <locale.h> 120 121int 122main(void) 123{ 124 (void) setlocale(LC_ALL, ""); 125 printf("%s\en", getlocalename_l(LC_ALL, LC_GLOBAL_LOCALE)); 126 return (0); 127} 128.Ed 129.Sh INTERFACE STABILITY 130.Sy Committed 131.Sh MT-LEVEL 132.Sy MT-Safe with Exceptions 133.Sh SEE ALSO 134.Xr locale 1 , 135.Xr freelocale 3C , 136.Xr newlocale 3C , 137.Xr setlocale 3C , 138.Xr uselocale 3C , 139.Xr locale 7 140