setlocale - Set the Locale of the Program

Syntax

#include <locale.h>
char *setlocale(int category, const char *locale);

Description

setlocale sets or queries the specified category of the program's locale. A locale is the complete definition of that part of a program that depends on language and cultural conventions.

The default locale is "C". You can accept the default, or you can use setlocale to set the locale to one of the supplied locales.

Note: The locale is global to all threads in a process, therefore a multithread process should not execute the setlocale function when other threads are executing for that process. The results are unpredictable if this occurs.

Some examples of the supplied locales as you would specify them for setlocale are:

• En_GB.IBM-850" (English, Great Britain, code page 850)
  
• Fr_CA.IBM-863" (French, France, code page 863)
  
• Ja_JP.IBM-932" (Japanese, Japan, code page 932)

The result of setlocale depends on the arguments you specify:

• The most general way to use setlocale is to specify a null string ("") for locale, for example, setlocale (LC_ALL, ""). setlocale then checks locale-related environment variables in the program's environment to find a locale name or names to use for category. To set a category to a specific locale, specify both the category and locale names. For example:

     setlocale(LC_CTYPE, "fr_fr.IBM-850");

  sets the LC_CTYPE category according to the "fr_fr.IBM-850" locale. The category names and their purpose are described in the table below.

  If locale name is not specified (NULL string), setlocale gets the locale name from:

  • LC_ALL, if it is defined and not null
    
  • The environment variable with the same name as category, if it is defined and not null
    
  • LANG, if it is defined and not null
    
  • If none of these variables is defined to a valid locale name, setlocale uses the system default locale.
  For example, if the LC_ALL environment variable is set to "De_DE" (Germany locale):

     setlocale(LC_TIME, "");
  

  sets the LC_TIME category to the "De_DE" locale.

  If category is LC_ALL and locale is a null string, setlocale checks the environment variables in the same order listed above. However, it checks the variable for each category and sets the category to the locale specified, which could be different for each category. (By contrast, if you specified LC_ALL and a specific locale name, all categories would be set to the same locale that you specify.) The string returned lists all the locales for all the categories.


To query the locale for a category, specify a null pointer for locale. setlocale then returns a string indicating the locale setting for that category, without changing it. For example:

   char *s = setlocale(LC_CTYPE, NULL);

returns the current locale for the LC_CTYPE category.

You can set the category argument of setlocale to one of these values: ┌─────────────┬───────────────────────────────────────────────────┐│Category │Purpose │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_ALL │ Specifies all categories associated with the pro- │
│ │ gram's locale. │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_COLLATE │ Affects the selection of the collation sequence; │
│ │ that is, the relative order of collation elements │
│ │ (characters and multicharacter collation ele- │
│ │ ments) in the program's locale. The collation │
│ │ sequence definition is used by regular │
│ │ expression, pattern matching, and sorting func- │
│ │ tions. Affects the regular expression functions │
│ │ regcomp and regexec; the string functions │
│ │ strcoll, strxfrm, wcscoll, and wcsxfrm. │
│ │ │
│ │ Because both LC_CTYPE and LC_COLLATE modify the │
│ │ same storage area, setting LC_CTYPE and │
│ │ LC_COLLATE to different categories causes unpre- │
│ │ dictable results. │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_CTYPE │ Defines the selection of character classification │
│ │ and case conversion for characters in the pro- │
│ │ gram's locale. Affects the behavior of │
│ │ character-handlingfunctionsdefinedinthe │
│ │ "<ctype.h>" header file: isalnum, isalpha, │
│ │ isblank, iswblank, iscntrl, isdigit, isgraph, │
│ │ islower, isprint, ispunct, isspace, isupper, │
│ │ iswalnum, iswalpha, iswcntrl, iswctype, iswdigit, │
│ │ iswgraph, iswlower, iswprint, iswpunct, iswspace, │
│ │ iswupper, iswxdigit, isxdigit, tolower, toupper, │
│ │ towlower, towupper, and wctype. │
│ │ │
│ │ Affects behavior of the printf and scanf families │
│ │ of functions: fprintf, printf, sprintf, vfprintf, │
│ │ vprintf, vsprintf, fscanf, scanf, and sscanf. │
│ │ │
│ │ Affects the behavior of wide character │
│ │ input/output functions: fgetwc, fgetws, getwc, │
│ │ getwchar, fputwc, fputws, putwc, putwchar, and │
│ │ ungetwc. │
│ │ │
│ │ Affects the behavior of multibyte and wide char- │
│ │ acter conversion functions: mblen, mbstowcs, │
│ │ mbtowc, wcstod, wcstol, wcstombs, wcstoul, │
│ │ wcswidth, wctomb, and wcwidth. │
│ │ │
│ │ Because both LC_CTYPE and LC_COLLATE modify the │
│ │ same storage area, setting LC_CTYPE and │
│ │ LC_COLLATE to different categories causes unpre- │
│ │ dictable results. │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_MESSAGES │ Affects the language of the messages. The │
│ │ setting is used by catopen, catgets, and │
│ │ catclose. Affects the values returned by │
│ │ nl_langinfo and also defines affirmative and neg- │
│ │ ative response patterns. │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_MONETARY │ Affects monetary information returned by │
│ │ localeconv and strfmon. It defines the rules and │
│ │ symbols used to format monetary numeric informa- │
│ │ tion in the program's locale. The formatting │
│ │ rules and symbols are strings. localeconv │
│ │ returns pointers to these strings with names │
│ │ found in the "<locale.h>" header file. │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_NUMERIC │ Affects the decimal-point character for the for- │
│ │ matted input/output and string conversion func- │
│ │ tions, and the nonmonetary formatting information │
│ │ returned by the localeconv function, │
│ │ specifically: │
│ │ │
│ │ printf family of functions │
│ │ scanf family of functions │
│ │ strtod │
│ │ atof. │
├─────────────┼───────────────────────────────────────────────────┤
│ LC_TIME │ Affects time and date format information in the │
│ │ program's locale, for the strftime, strptime, and │
│ │ wcsftime functions. │
└─────────────┴───────────────────────────────────────────────────┘


Returns

setlocale returns a string that specifies the locale for the category. If you specified "" for locale, the string names the current locale that has been configured; otherwise, it indicates the new locale that the category was set to.

If you specified LC_ALL for category, the returned string can be either a single locale name or a list of the locale names for each category in the following order:

• LC_COLLATE
  
• LC_CTYPE
  
• LC_NUMERIC
  
• LC_MONETARY
  
• LC_TIME
  
• LC_MESSAGES

The string can be used on a subsequent call to restore that part of the program's locale. Because the returned string can be overwritten by subsequent calls to setlocale, you should copy the string if you plan to use it later.

If an error occurs, setlocale returns NULL and does not alter the program's locale. Errors can occur if the category or locale is not valid, or if the value of the environment variable for a category does not contain a valid locale.

Example Code

This example sets the locale of the program to be "fr_fr.ibm-850" and prints the string that is associated with the locale.

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

int main(void)
{
   char *string;

   if (NULL == (string = setlocale(LC_ALL, "fr_fr.ibm-850")))
      printf("setlocale failed.\n");
   else
      printf("The current locale is set to %s.\n", string);
   return 0;

   /****************************************************************************
      The output should be similar to :

      The current locale is set to fr_fr.ibm-850.
   ****************************************************************************/
}

This example uses setenv to set the value of the environment variable LC_TIME to FRAN, calls setlocale to set all categories to default values, then query all categories, and uses printf to print results.

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

int main(void)
{
   char *string;

   if (NULL == (string = setlocale(LC_TIME, "fr_fr")))
      printf("setlocale failed.\n");
   else
      printf("The current locale categories are: \"%s\"\n", string);
   return 0;

   /****************************************************************************
      Assuming that the default setting is en_us, the output should be similar to :

      The current locale categories are: "en_us en_us en_us en_us fr_fr en_us"
   ****************************************************************************/
}

Related Information

• Introduction to Locale" in the Programming Guide
  
• getenv
  
• localeconv

---

[Back: setjmp - Preserve Environment]
[Next: _setmode - Set File Translation Mode]