Edit

Share via

Locale

  • Article

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, isw 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 long value 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.

See also

Internationalization
Universal C runtime routines by category