function
<clocale>

setlocale

char* setlocale (int category, const char* locale);
Set or retrieve locale
Sets locale information to be used by the current program, either changing the entire locale or portions of it. The function can also be used to retrieve the current locale's name by passing NULL as the value for argument locale.

Locales contain information on how to interpret and perform certain input/output and transformation operations taking into consideration location and language specific settings.

Most running environments have certain locale information set according to the user preferences or localization. But, independently of this system locale, on start, all C programs have the "C" locale set, which is a rather neutral locale with minimal locale information that allows the result of programs to be predictable. In order to use the default locale set in the environment, this function can be called with "" as argument locale.

On program startup, the locale selected is the "C" locale, which is the same as would be set by calling setlocale(LC_ALL,"C").

The locale settings selected in the environment can be selected by calling setlocale(LC_ALL,"").

The portions of the current locale affected by a call to this function are specified by argument category.

Parameters

category
Portion of the locale affected. It is one of the following constant values defined as macros in <clocale>:
valuePortion of the locale affected
LC_ALLThe entire locale.
LC_COLLATEAffects the behavior of strcoll and strxfrm.
LC_CTYPEAffects character handling functions (all functions of <cctype>, except isdigit and isxdigit), and the multibyte and wide character functions.
LC_MONETARYAffects monetary formatting information returned by localeconv.
LC_NUMERICAffects the decimal-point character in formatted input/output operations and string formatting functions, as well as non-monetary information returned by localeconv.
LC_TIMEAffects the behavior of strftime.
locale
C string containing the name of a C locale. These are system specific, but at least the two following locales must exist:
locale namedescription
"C"Minimal "C" locale
""Environment's default locale
If the value of this parameter is NULL, the function does not make any changes to the current locale, but the name of the current locale is still returned by the function.

Return Value

On success, A pointer to a C string identifying the locale currently set for the category. If category is LC_ALL and different portions of the locale are set to different values, the string returned gives this information in a format which may vary between library implementations.

If the function failed to set a new locale, this is not modified and a null pointer is returned.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
/* setlocale example */
#include <stdio.h>      /* printf */
#include <time.h>       /* time_t, struct tm, time, localtime, strftime */
#include <locale.h>     /* struct lconv, setlocale, localeconv */

int main ()
{
  time_t rawtime;
  struct tm * timeinfo;
  char buffer [80];

  struct lconv * lc;

  time ( &rawtime );
  timeinfo = localtime ( &rawtime );

  int twice=0;

  do {
    printf ("Locale is: %s\n", setlocale(LC_ALL,NULL) );

    strftime (buffer,80,"%c",timeinfo);
    printf ("Date is: %s\n",buffer);

    lc = localeconv ();
    printf ("Currency symbol is: %s\n-\n",lc->currency_symbol);

    setlocale (LC_ALL,"");
  } while (!twice++);

  return 0;
}


One of the possible outputs when the previous code is run is:
Locale is: C
Date is: 01/15/07 13:33:47
Currency symbol is: 
-
Locale is: English_United States.1252
Date is: 1/15/07 1:33:47 PM
Currency symbol is: $
-

Data races

Changing locale settings may introduce data races with concurrent calls to the same function or to any C-library function affected by the locale.

Exceptions (C++)

No-throw guarantee: this function never throws exceptions.

See also

localeconv
Get locale formatting parameters for quantities (function )