NAME

getlocalename_l — get name of locale

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <locale.h>

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

DESCRIPTION

The getlocalename_l() function returns the name of the specific category of the specified locale. If locale is LC_GLOBAL_LOCALE, then information will be returned about the current global locale. The global locale is changed by calls to setlocale(3C) and not impacted by a thread calling uselocale(3C).

When the category is LC_ALL, the returned string is a form that when passed to setlocale(3C) it will result in the same locale being activated. Similarly, passing this locale to newlocale(3C) will result in a comparable locale. Note, the latter is not strictly guaranteed by POSIX so portable applications may not want to rely on this behavior.

The returned string's lifetime and the validity of the pointer is tied to the lifetime of the locale itself. This varies depending on whether this refers to the global locale or not. If it is not the global locale, calling either newlocale(3C) or freelocale(3C) on locale, means that the string is no longer valid.

When querying the global locale, data lifetimes are more complicated. It is possible that calls to the getlocalename_l() function may race with other threads calling setlocale(3C). The returned data will always be valid; however, depending on the interleaving of thread execution, the returned name may be from the prior locale during a contemporaneous setlocale(3C). This is the exception to the thread safety documented for this function. Portable applications should assume that data returned related to the global locale may be invalidated by the calling thread exiting or calling getlocalename_l() again with LC_GLOBAL_LOCALE.

RETURN VALUES

Upon successful completion, the getlocalename_l() returns the name of the category of locale. Otherwise, NULL is returned.

EXAMPLES

Example 1 Printing the current thread's locale.

This example queries the current thread's locale; however, it does not call freelocale(3C). Locales that are queried at run-time are still in use and therefore should not be freed. Instead, the logic that set the locale should free it after it changes the locale again.

#include <stdio.h>
#include <locale.h>

void
print_locale(void)
{
        locale_t loc = uselocale(NULL);
        printf("%s\n", getlocalename_l(LC_ALL, LC_GLOBAL_LOCALE));
}

Example 2 Printing the global locale.

#include <stdio.h>
#include <locale.h>

int
main(void)
{
        (void) setlocale(LC_ALL, "");
        printf("%s\n", getlocalename_l(LC_ALL, LC_GLOBAL_LOCALE));
        return (0);
}

INTERFACE STABILITY

Committed

MT-LEVEL

MT-Safe with Exceptions