_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l
Convert a string to lowercase. These functions are deprecated because more secure versions are available; see _strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l.
char *_strlwr( char * str ); wchar_t *_wcslwr( wchar_t * str ); unsigned char *_mbslwr( unsigned char * str ); char *_strlwr_l( char * str, _locale_t locale ); wchar_t *_wcslwr_l( wchar_t * str, _locale_t locale ); unsigned char *_mbslwr_l( unsigned char * str, _locale_t locale ); template <size_t size> char *_strlwr( char (&str)[size] ); // C++ only template <size_t size> wchar_t *_wcslwr( wchar_t (&str)[size] ); // C++ only template <size_t size> unsigned char *_mbslwr( unsigned char (&str)[size] ); // C++ only template <size_t size> char *_strlwr_l( char (&str)[size], _locale_t locale ); // C++ only template <size_t size> wchar_t *_wcslwr_l( wchar_t (&str)[size], _locale_t locale ); // C++ only template <size_t size> unsigned char *_mbslwr_l( unsigned char (&str)[size], _locale_t locale ); // C++ only
Parameters
- str
-
Null-terminated string to convert to lowercase.
- locale
-
The locale to use.
The _strlwr function converts any uppercase letters in str to lowercase as determined by the LC_CTYPE category setting of the locale. Other characters are not affected. For more information on LC_CTYPE, see setlocale. The versions of these functions without the _l suffix use the current locale for their locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale passed in instead.
The _wcslwr and _mbslwr functions are wide-character and multibyte-character versions of _strlwr. The argument and return value of _wcslwr are wide-character strings; those of _mbslwr are multibyte-character strings. These three functions behave identically otherwise.
If str is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation . If execution is allowed to continue, these functions return the original string and set errno to EINVAL.
In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure Template Overloads.
| TCHAR.H routine | _UNICODE & _MBCS not defined | _MBCS defined | _UNICODE defined |
|---|---|---|---|
| _tcslwr | _strlwr | _mbslwr | _wcslwr |
| _tcslwr_l | _strlwr_l | _mbslwr_l | _wcslwr_l |
| Routine | Required header | Compatibility |
|---|---|---|
| _strlwr, _strlwr_l | <string.h> | Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 |
| _wcslwr, _wcslwr_l | <string.h> or <wchar.h> | Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 |
| _mbslwr, _mbslwr_l | <mbstring.h> | Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 |
For additional compatibility information, see Compatibility in the Introduction.
// crt_strlwr.c
// compile with: /W3
// This program uses _strlwr and _strupr to create
// uppercase and lowercase copies of a mixed-case string.
#include <string.h>
#include <stdio.h>
int main( void )
{
char string[100] = "The String to End All Strings!";
char * copy1 = _strdup( string ); // make two copies
char * copy2 = _strdup( string );
_strlwr( copy1 ); // C4996
// Note: _strlwr is deprecated; consider using _strlwr_s instead
_strupr( copy2 ); // C4996
// Note: _strupr is deprecated; consider using _strupr_s instead
printf( "Mixed: %s\n", string );
printf( "Lower: %s\n", copy1 );
printf( "Upper: %s\n", copy2 );
free( copy1 );
free( copy2 );
}
Output
Mixed: The String to End All Strings! Lower: the string to end all strings! Upper: THE STRING TO END ALL STRINGS!
