Tribblix: manual page: getlocalename

GETLOCALENAME_L(3C) Standard C Library Functions GETLOCALENAME_L(3C)

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