Locale
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Locale.
Locale* refers to country/region and language settings that you can use to customize your program. Some locale-dependent categories include the display formats for dates and monetary values. For more information, see Locale Categories.
Use the setlocale function to change or query some or all of the current program or thread locale information while using functions without the _l suffix. The functions with the _l suffix will use the locale parameter passed in for their locale information during the execution of that specific function only. To create a locale for use with a function with a _l suffix, use _create_locale. To free this locale, use _free_locale. To get the current locale, use _get_current_locale.
Use _configthreadlocale to control whether each thread has its own locale, or all threads in a program share the same locale. For more information, see Locales and Code Pages.
More secure versions of the functions in the following table are available, indicated by the _s ("secure") suffix. For more information, see Security Features in the CRT.
Locale-Dependent Routines
| Routine | Use | setlocale category setting dependence |
|---|---|---|
| atof, _atof_l, _wtof, _wtof_l | Convert character to floating-point value | LC_NUMERIC |
| atoi, _atoi_l, _wtoi, _wtoi_l | Convert character to integer value | LC_NUMERIC |
| _atoi64, _atoi64_l, _wtoi64, _wtoi64_l | Convert character to 64-bit integer value | LC_NUMERIC |
| atol, _atol_l, _wtol, _wtol_l | Convert character to long value | LC_NUMERIC |
| _atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l | Convert character to double-long value | LC_NUMERIC |
| is Routines | Test given integer for particular condition. | LC_CTYPE |
| isleadbyte, _isleadbyte_l | Test for lead byte | LC_CTYPE |
| localeconv | Read appropriate values for formatting numeric quantities | LC_MONETARY, LC_NUMERIC |
| MB_CUR_MAX | Maximum length in bytes of any multibyte character in current locale (macro defined in STDLIB.H) | LC_CTYPE |
| _mbccpy, _mbccpy_l,_mbccpy_s, _mbccpy_s_l | Copy one multibyte character | LC_CTYPE |
| _mbclen, mblen, _mblen_l | Validate and return number of bytes in multibyte character | LC_CTYPE |
| strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l | For multibyte-character strings: validate each character in string; return string length | LC_CTYPE |
| mbstowcs, _mbstowcs_l,mbstowcs_s, _mbstowcs_s_l | Convert sequence of multibyte characters to corresponding sequence of wide characters | LC_CTYPE |
| mbtowc, _mbtowc_l | Convert multibyte character to corresponding wide character | LC_CTYPE |
| printf functions | Write formatted output | LC_NUMERIC (determines radix character output) |
| scanf functions | Read formatted input | LC_NUMERIC (determines radix character recognition) |
| setlocale, _wsetlocale | Select locale for program | Not applicable |
| strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l | Compare characters of two strings | LC_COLLATE |
| _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l | Compare two strings without regard to case | LC_CTYPE |
| _stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _wcsicoll_l, _mbsicoll_l | Compare characters of two strings (case insensitive) | LC_COLLATE |
| _strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l | Compare first n characters of two strings |
LC_COLLATE |
| _strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l | Compare characters of two strings without regard to case. | LC_CTYPE |
| _strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l | Compare first n characters of two strings (case insensitive) |
LC_COLLATE |
| strftime, wcsftime, _strftime_l, _wcsftime_l | Format date and time value according to supplied format argument |
LC_TIME |
| _strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l,_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l | Convert, in place, each uppercase letter in given string to lowercase | LC_CTYPE |
| strtod, _strtod_l, wcstod, _wcstod_l | Convert character string to double value |
LC_NUMERIC (determines radix character recognition) |
| strtol, wcstol, _strtol_l, _wcstol_l | Convert character string to longvalue |
LC_NUMERIC (determines radix character recognition) |
| strtoul, _strtoul_l, wcstoul, _wcstoul_l | Convert character string to unsigned long value | LC_NUMERIC (determines radix character recognition) |
| _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr,_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l | Convert, in place, each lowercase letter in string to uppercase | LC_CTYPE |
| strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l | Transform string into collated form according to locale | LC_COLLATE |
| tolower, _tolower, towlower, _tolower_l, _towlower_l,_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l | Convert given character to corresponding lowercase character | LC_CTYPE |
| toupper, _toupper, towupper, _toupper_l, _towupper_l,_mbctolower, _mbctolower_l, _mbctoupper, _mbctoupper_l | Convert given character to corresponding uppercase letter | LC_CTYPE |
| wcstombs, _wcstombs_l,wcstombs_s, _wcstombs_s_l | Convert sequence of wide characters to corresponding sequence of multibyte characters | LC_CTYPE |
| wctomb, _wctomb_l,wctomb_s, _wctomb_s_l | Convert wide character to corresponding multibyte character | LC_CTYPE |
Note
For multibyte routines, the multibyte code page must be equivalent to the locale set with setlocale. _setmbcp, with an argument of _MB_CP_LOCALE makes the multibyte code page the same as the setlocale code page.