Managing System Locales

Please tell us how to improve our documentation:

Thank you for your feedback! If you want to participate in content improvement and share additional information, please click Feedback button.

Rate this document:

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.3.

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
localelist(): Query installed locales
localelistfree(): Free memory associated with a localelist() call

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.3.

For more information, see the setlocale(3C), localelist(3C), localelistfree(3C), environ(5), locale_alias(5), 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.

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(): Retrieve language and the locale information
strftime(): Convert date and time to a string
strptime(): Convert character string to a time structure
strfmon(): 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 4 Obtaining the Codeset Name of a Locale

The following code fragment shows how to obtain the codeset of the current program's locale.

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

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 5 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 for the affirmative response of the current locale.

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

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

Example 6 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);
}