NAME

getlocalename_l — get a locale name from a locale object

SYNOPSIS

[CX] #include <locale.h>

const char *getlocalename_l(int category, locale_t locobj);

DESCRIPTION

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.

RETURN VALUE

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().

ERRORS

No errors are defined.

EXAMPLES

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);

APPLICATION USAGE

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.

RATIONALE

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.

FUTURE DIRECTIONS

None.

SEE ALSO

freelocale, newlocale, setlocale, uselocale

XBD 7. Locale, <locale.h>

CHANGE HISTORY

First released in Issue 8.