setlocale, _wsetlocale

Article
09/15/2006

Define the locale.

char*setlocale(intcategory**,constchar*locale);**

wchar_t*_wsetlocale(intcategory**,constwchar_t*locale);**

Routine	Required Header	Compatibility
setlocale	<locale.h>	ANSI, Win 95, Win NT
_wsetlocale	<locale.h> or <wchar.h>	Win 95, Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB	Single thread static library, retail version
LIBCMT.LIB	Multithread static library, retail version
MSVCRT.LIB	Import library for MSVCRT.DLL, retail version

Return Value

If a valid locale and category are given, the function returns a pointer to the string associated with the specified locale and category. If the locale or category is invalid, the function returns a null pointer and the current locale settings of the program are not changed.

For example, the call

setlocale( LC_ALL, "English" );

sets all categories, returning only the string English_USA.1252. If all categories are not explicitly set by a call to setlocale, the function returns a string indicating the current setting of each of the categories, separated by semicolons. If the locale argument is a null pointer, setlocale returns a pointer to the string associated with the category of the program’s locale; the program’s current locale setting is not changed.

The null pointer is a special directive that tells setlocale to query rather than set the international environment. For example, the sequence of calls

// Set all categories and return "English_USA.1252"
setlocale( LC_ALL, "English" );
// Set only the LC_MONETARY category and return "French_France.1252"
setlocale( LC_MONETARY, "French" );
setlocale( LC_ALL, NULL );

returns

LC_COLLATE=English_USA.1252;
LC_CTYPE=English_USA.1252;
LC_MONETARY=French_France.1252;
LC_NUMERIC=English_USA.1252;
LC_TIME=English_USA.1252

which is the string associated with the LC_ALL category.

You can use the string pointer returned by setlocale in subsequent calls to restore that part of the program’s locale information, assuming that your program does not alter the pointer or the string. Later calls to setlocale overwrite the string; you can use _strdup to save a specific locale string.

Parameters

category

Category affected by locale

locale

Locale name

Remarks

Use the setlocale function to set, change, or query some or all of the current program locale information specified by locale and category. “Locale” refers to the locality (country and language) for which you can customize certain aspects of your program. Some locale-dependent categories include the formatting of dates and the display format for monetary values.

_wsetlocale is a wide-character version of setlocale; the locale argument and return value of _wsetlocale are wide-character strings. _wsetlocale and setlocale behave identically otherwise.

Generic-Text Routine Mappings

TCHAR.H Routine	_UNICODE & _MBCS Not Defined	_MBCS Defined	_UNICODE Defined
_tsetlocale	setlocale	setlocale	_wsetlocale

The category argument specifies the parts of a program’s locale information that are affected. The macros used for category and the parts of the program they affect are as follows:

LC_ALL

All categories, as listed below

LC_COLLATE

The strcoll, _stricoll, wcscoll, _wcsicoll, and strxfrm functions

LC_CTYPE

The character-handling functions (except isdigit, isxdigit, mbstowcs, and mbtowc, which are unaffected)

LC_MONETARY

Monetary-formatting information returned by the localeconv function

LC_NUMERIC

Decimal-point character for the formatted output routines (such as printf), for the data-conversion routines, and for the nonmonetary-formatting information returned by localeconv

LC_TIME

The strftime and wcsftime functions

The locale argument is a pointer to a string that specifies the name of the locale. If locale points to an empty string, the locale is the implementation-defined native environment. A value of “C” specifies the minimal ANSI conforming environment for C translation. The “C” locale assumes that all char data types are 1 byte and that their value is always less than 256. The “C” locale is the only locale supported in Microsoft Visual C++ version 1.0 and earlier versions of Microsoft C/C++. Microsoft Visual C++ supports all the locales listed in Appendix A, Language and Country Strings. At program startup, the equivalent of the following statement is executed:

setlocale( LC_ALL, "C" );

The locale argument takes the following form:

locale :: "lang[_country[.code_page]]"
            | ".code_page"
            | ""
            | NULL

The set of available languages, countries, and code pages includes all those supported by the Win32 NLS API. The set of language and country codes supported by setlocale is listed in Appendix A, Language and Country Strings.

If locale is a null pointer, setlocale queries, rather than sets, the international environment, and returns a pointer to the string associated with the specified category. The program’s current locale setting is not changed. For example,

setlocale( LC_ALL, NULL );

returns the string associated with category.

The following examples pertain to the LC_ALL category. Either of the strings ".OCP" and ".ACP" can be used in place of a code page number to specify use of the system default OEM code page and system-default ANSI code page, respectively.

setlocale( LC_ALL, "" );

Sets the locale to the default, which is the system-default ANSI code page obtained from the operating system.

setlocale( LC_ALL, ".OCP" );

Explicitly sets the locale to the current OEM code page obtained from the operating system.

setlocale( LC_ALL, ".ACP" );

Sets the locale to the ANSI code page obtained from the operating system.

setlocale( LC_ALL, "[lang_ctry]" );

Sets the locale to the language and country indicated, using the default code page obtained from the host operating system.

setlocale( LC_ALL, "[lang_ctry.cp]" );

Sets the locale to the language, country, and code page indicated in the [lang_ctry.cp] string. You can use various combinations of language, country, and code page. For example:

setlocale( LC_ALL, "French_Canada.1252" );
// Set code page to French Canada ANSI default
setlocale( LC_ALL, "French_Canada.ACP" );
// Set code page to French Canada OEM default
setlocale( LC_ALL, "French_Canada.OCP" );

setlocale( LC_ALL, "[lang]" );

Sets the locale to the country indicated, using the default country for the language specified, and the system-default ANSI code page for that country as obtained from the host operating system. For example, the following two calls to setlocale are functionally equivalent:

setlocale( LC_ALL, "English" );
setlocale( LC_ALL, "English_United States.1252" );

setlocale( LC_ALL, "[.code_page]" );

Sets the code page to the value indicated, using the default country and language (as defined by the host operating system) for the specified code page.

The category must be either LC_ALL or LC_CTYPE to effect a change of code page. For example, if the default country and language of the host operating system are “United States” and “English,” the following two calls to setlocale are functionally equivalent:

setlocale( LC_ALL, ".1252" );
setlocale( LC_ALL, "English_United States.1252");

For more information see thesetlocale pragma in Preprocessor Reference.

Example

/* LOCALE.C: Sets the current locale to "Germany" using the
 * setlocale function and demonstrates its effect on the strftime
 * function.
 */

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

void main(void)
{
       time_t ltime;
       struct tm *thetime;
       unsigned char str[100];

       setlocale(LC_ALL, "German");
       time (&ltime);
       thetime = gmtime(&ltime);

       /* %#x is the long date representation, appropriate to
        * the current locale
        */
       if (!strftime((char *)str, 100, "%#x",
                     (const struct tm *)thetime))
               printf("strftime failed!\n");
       else
               printf("In German locale, strftime returns '%s'\n",
                      str);

       /* Set the locale back to the default environment */
       setlocale(LC_ALL, "C");
       time (&ltime);
       thetime = gmtime(&ltime);

       if (!strftime((char *)str, 100, "%#x",
                     (const struct tm *)thetime))
               printf("strftime failed!\n");
       else
               printf("In 'C' locale, strftime returns '%s'\n",
                      str);
}

Output

In German locale, strftime returns 'Donnerstag, 22. April 1993'
In 'C' locale, strftime returns 'Thursday, April 22, 1993'

Locale Routines

Share via

setlocale, _wsetlocale

Additional resources