Managing System Locales

Language:

The locale setting of an application determines how the application behaves in different locales. The locale setting is the single most important setting when dealing with internationalized applications. From a user's perspective, the locale affects many aspects of application's behavior, and from the programmer's perspective, it affects the behavior of many interfaces that the system provides. Properly written internationalized applications need to correctly set the locale.

For more information about locales and how they affect a program's behavior, see International Language Environments Guide for Oracle Solaris 11.4.

Caution - All the internationalized interfaces are MT-Safe with exceptions as mentioned in the setlocale(3C) man page. For more information about interface classification, see MT Interface Safety Levels in Multithreaded Programming Guide.

Locale-Sensitive Functions

The functions described in this book are locale sensitive. The output of the functions depends on the locale of the process.

In a C program, the locale is set by using the setlocale() function. The setlocale() function must be called early in a program so that other functions can use the locale information.

Note - If you do not set any locale in your program, by default the program runs in the C locale. For more information about the C locale, see C Locale.

Locale Functions

The functions related to system locales are as follows:

setlocale(): Set the program locale.
newlocale(): Create or modify a locale object.
uselocale(): Use locale in current thread.
duplocale(): Duplicate a locale object.
freelocale(): Free resources allocated for a locale object.
localelist(): Query installed locales
localelistfree(): Free memory associated with a localelist() call

The newlocale(), uselocale(), duplocale(), and freelocale() enable more flexible uses of locales than what setlocale() enables. Especially in multithreaded applications, changing a locale with setlocale() after created threads is problematic because the function call affects the entire application process. If your application can change a locale after it has created threads, consider using one of the following new styles of locale use instead:

Create a locale object with newlocale() or duplocale(). Then call uselocale() to specify the object as the locale of current thread. After the thread locale is set, all locale sensitive functions behave based on the thread locale, instead of processing the global locale that is set with setlocale(). See Example 4, Setting or Changing Thread Locale Using uselocale.
Create a locale object with newlocale() or duplocale(). Then, pass the object as argument of functions that accept explicit locale specifications. Those functions have suffix _l in their names. For example, isalnum_l()(c, locale) explicitly accepts locale as an argument. However isalnum()(c) obtains locale information from the current thread or process. This approach has similarities with other languages such as Java. See Example 5, EXAMPLE 5 Passing Locale Object to *_l Variant of Function. However, if the function you want to use does not have the _l variant, then use the preceding option instead.

The localelist() function is used to query the locales which are installed on a system. For information about how to install additional locales on an Oracle Solaris system, see International Language Environments Guide for Oracle Solaris 11.4.

For more information, see the setlocale(3C), localelist(3C),newlocale(3C), uselocale(3C), duplocale(3C), freelocale(3C), localelistfree(3C), environ(7), locale_alias(7), langinfo.h(3HEAD), and nl_types.h(3HEAD) man pages.

Example 1 Setting the Locale of a Program

The following code fragment shows how to set the locale to en_US.UTF-8.

#include <locale.h>
      :
(void) setlocale(LC_ALL, "en_US.UTF-8");

Note - If you want to use the locale information from the user environment, pass an empty string ("") as an argument to the setlocale() function. For information, see the setlocale(3C) and environ(5) man pages.

Example 2 Querying the Locale of a Program

The following code fragment shows how to query the current locale.

   
#include <locale.h>
      :
char *locale;
      :
locale = setlocale(LC_ALL, NULL);

In this example, the locale variable is set to the current locale of the program.

Example 3 Using the Locale Settings From the User Environment

The following code fragment shows how to set the env_locale variable to use the locale settings from the user environment.

   
#include <locale.h>
      :
char *env_locale;
env_locale = setlocale(LC_ALL, "");

For example, if the locale in the user environment is es_ES.UTF-8, the env_locale variable is set to es_ES.UTF-8.

Note - When the environment has different values set for different locale categories (also called the composite locale setting), the call to the setlocale function with the LC_ALL category, returns a string that contains values for all the categories separated by the slash character "/". For example:

"/es_ES.UTF-8/es_ES.UTF-8/es_ES.UTF-8/es_ES.UTF-8/es_ES.UTF-8/de_DE.UTF-8"

This string includes the categories LC_CTYPE, LC_NUMERIC,LC_TIME, LC_COLLATE, LC_MONETARY, and LC_MESSAGES, where LC_MESSAGES was set in the environment to de_DE.UTF-8.

Example 4 Setting or Changing Thread Locale Using uselocale()

This example shows how to set the thread locale.

   #include <locale.h>
.
.
    locale_t loc;
.
.
    loc = newlocale(LC_ALL_MASK, locale_name, (locale_t)0); /* create a locale object */
    uselocale(loc); /* set current thread's locale */
.
.
   if (isalnum(c)) { /* behaves based on the thread's current locale */

Example 5 EXAMPLE 5 Passing Locale Object to *_l() Variant of Function

This example shows how to pass the local object explicitly.

   #include <locale.h>
.
.
    locale_t loc;
.
.
    loc = newlocale(LC_ALL_MASK, locale_name, (locale_t)0); /* create a locale object */
.
.
    if (isalnum_l(c, loc)) { /* behaves based on loc passed as argument */
.
.

Functions for Retrieving and Formatting the Locale Data

The functions to retrieve and format the locale data are as follows:

localeconv(): Retrieve numeric formatting information.
nl_langinfo()
nl_langinfo_l(): Retrieve language and the locale information.
strftime()
strftime_l(): Convert date and time to a string.
strptime(): Convert character string to a time structure.
strfmon()
strfmon_l(): Convert monetary value to a string.

These functions are used to query locale-specific data, such as the time format or currency symbol. The functions can also be used to format time, numeric, or monetary information according to regional conventions. For more information, see the langinfo.h(3HEAD) and mktime(3C) man pages.

Example 6 Obtaining the Codeset Name of a Locale

The following code fragment shows how to obtain the codeset involving one of the following cases:

Current thread's locale
Current program's locale in the case of nl_langinfo()
Locale specified as loc in the case of nl_langinfo_l()

#include <langinfo.h>
:
char *cs;
cs = nl_langinfo(CODESET);

Or:

#include <langinfo.h>
:
char *cs;
cs = nl_langinfo(CODESET, loc);

In this example, for the C locale, the cs variable points to the string "646", which is the canonical name for the US-ASCII codeset. For more information about codesets, see Converting Codesets.

Example 7 Querying the Affirmative Response String of a Locale

The following code fragment shows how to set the yesstr variable to the yes/no string, which is used in the following cases:

In the case of the nl_langinfo() function, the affirmative response of the current thread's or current program's locale.
In the case of the nl_langinfo_l() function, the affirmative response of the locale as specified as loc.

#include <langinfo.h>
:
char *yesstr;
yesstr = nl_langinfo(YESSTR);

Or:

#include <langinfo.h>
:
char *yesstr;
yesstr = nl_langinfo(YESSTR, loc);

For example, in the es_ES.UTF-8 locale, yesstr will point to the string sí.

Example 8 Printing the Local Time

The following code fragment shows how to display the current date and time formatted according to the regional conventions of the locale that is set for the environment.

#include <stdio.h>
#include <locale.h>
#include <time.h>
   :
char    *locale, ftime[BUFSIZ];
time_t  t;

locale = setlocale(LC_ALL, "");
if (locale == NULL) {
/* handle error */
}

if (0 != strftime(ftime, BUFSIZ, (char *)NULL, localtime(&t))) {
(void) printf("%s - %s\n", locale, ftime);
}