getlocalename_l — get a locale name from a locale object
If category is not LC_ALL, the getlocalename_l() function shall return the locale name for the given locale category of the locale object locobj, or of the global locale if locobj is the special locale object LC_GLOBAL_LOCALE.
If category is LC_ALL, the getlocalename_l() function shall return a string that encodes the locale settings for all locale categories of the locale object locobj, or of the global locale if locobj is the special locale object LC_GLOBAL_LOCALE, in the same form as is returned by setlocale(). The string returned is such that a subsequent call to setlocale(), from the same process, with a pointer to that string as locale and the LC_ALL category shall set the global locale to the same locale for each category as was present in the queried object.
If the value of the category argument is neither LC_ALL nor a supported locale category value (see setlocale ), getlocalename_l() shall fail.
The behavior is undefined if the locobj argument is neither the special locale object LC_GLOBAL_LOCALE nor a valid locale object handle.
Upon successful completion, getlocalename_l() shall return a pointer to a string; otherwise, a null pointer shall be returned.
If locobj is LC_GLOBAL_LOCALE, the returned string pointer might be invalidated or the string content might be overwritten by a subsequent call in the same thread to getlocalename_l() with LC_GLOBAL_LOCALE; the returned string pointer might also be invalidated if the calling thread is terminated. Otherwise, the returned string pointer and content shall remain valid until the locale object locobj is used in a call to freelocale() or as the base argument in a successful call to newlocale().
No errors are defined.
Determining the locale name for a category of the current locale
The following example shows how to obtain the locale name for the LC_NUMERIC category of the current thread-local locale, or of the global locale if no thread-local locale is in use.
#include <locale.h> ... const char *name; locale_t loc = uselocale(NULL); name = getlocalename_l(LC_NUMERIC, loc);
In addition to the caveats regarding validity of the returned string pointer in RETURN VALUE, the content of the string returned when category is LC_ALL is only required to be valid for the life of the process, so is not intended for storage or sharing between processes. As the internal format of the string is implementation-specific, there is nothing preventing a subsequent run of an application from being presented a different format, for example if the implementation is updated.
Historical versions of getlocalename_l() did not handle the special locale object LC_GLOBAL_LOCALE, requiring that applications used setlocale(category, NULL) to query the global locale if uselocale(NULL) returned LC_GLOBAL_LOCALE. However, since setlocale() is not required to be thread-safe (even when the only concurrent calls are ones that query the locale), this method was problematic for multi-threaded processes. This standard requires that getlocalename_l(category, LC_GLOBAL_LOCALE) queries the global locale in a thread-safe manner, for example by returning a pointer to a thread-local internal buffer instead of a process-wide internal buffer.
None.
freelocale , newlocale , setlocale , uselocale
XBD 7. Locale , <locale.h>
First released in Issue 8.
return to top of page