Locale

The "Locale" refers to the locality (the Country/Region, 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. 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 Enhancements 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, strlen_l, wcslen, wcslen_l, _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.

See Also

Reference

Internationalization

Run-Time Routines by Category