_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l

Converts a string to lowercase, by using the current locale or a locale object that's passed in. These versions of _strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l have security enhancements, as described in Security features in the CRT.

Important

_mbslwr_s and _mbslwr_s_l cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported in Universal Windows Platform apps.

Syntax

errno_t _strlwr_s(
   char *str,
   size_t numberOfElements
);
errno_t _strlwr_s_l(
   char *str,
   size_t numberOfElements,
   _locale_t locale
);
errno_t _mbslwr_s(
   unsigned char *str,
   size_t numberOfElements
);
errno_t _mbslwr_s_l(
   unsigned char *str,
   size_t numberOfElements,
   _locale_t locale
);
errno_t _wcslwr_s(
   wchar_t *str,
   size_t numberOfElements
);
errno_t _wcslwr_s_l(
   wchar_t *str,
   size_t numberOfElements,
   _locale_t locale
);
template <size_t size>
errno_t _strlwr_s(
   char (&str)[size]
); // C++ only
template <size_t size>
errno_t _strlwr_s_l(
   char (&str)[size],
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbslwr_s(
   unsigned char (&str)[size]
); // C++ only
template <size_t size>
errno_t _mbslwr_s_l(
   unsigned char (&str)[size],
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _wcslwr_s(
   wchar_t (&str)[size]
); // C++ only
template <size_t size>
errno_t _wcslwr_s_l(
   wchar_t (&str)[size],
   _locale_t locale
); // C++ only

Parameters

str
Null-terminated string to convert to lowercase.

numberOfElements
Size of the buffer.

locale
The locale to use.

Return value

Zero if successful; a non-zero error code on failure.

These functions validate their parameters. If str isn't a valid null-terminated string, the invalid parameter handler is invoked, as described in Parameter validation . If execution is allowed to continue, the functions return EINVAL and set errno to EINVAL. If numberOfElements is less than the length of the string, the functions also return EINVAL and set errno to EINVAL.

Remarks

The _strlwr_s function converts, in place, any uppercase letters in str to lowercase. _mbslwr_s is a multi-byte character version of _strlwr_s. _wcslwr_s is a wide-character version of _strlwr_s.

The output value is affected by the setting of the LC_CTYPE category setting of the locale. For more information, see setlocale. The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. For more information, see Locale.

In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see Secure template overloads.

The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use _CrtSetDebugFillThreshold.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Generic-text routine mappings

TCHAR.H routine	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
_tcslwr_s	_strlwr_s	_mbslwr_s	_wcslwr_s
_tcslwr_s_l	_strlwr_s_l	_mbslwr_s_l	_wcslwr_s_l

Requirements

Routine	Required header
_strlwr_s, _strlwr_s_l	<string.h>
_mbslwr_s, _mbslwr_s_l	<mbstring.h>
_wcslwr_s, _wcslwr_s_l	<string.h> or <wchar.h>

For more compatibility information, see Compatibility.

Example

// crt_strlwr_s.cpp
// This program uses _strlwr_s and _strupr_s to create
// uppercase and lowercase copies of a mixed-case string.
//

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

int main()
{
   char str[] = "The String to End All Strings!";
   char *copy1, *copy2;
   errno_t err;

   err = _strlwr_s( copy1 = _strdup(str), strlen(str) + 1);
   err = _strupr_s( copy2 = _strdup(str), strlen(str) + 1);

   printf( "Mixed: %s\n", str );
   printf( "Lower: %s\n", copy1 );
   printf( "Upper: %s\n", copy2 );

   free( copy1 );
   free( copy2 );

   return 0;
}

Mixed: The String to End All Strings!
Lower: the string to end all strings!
Upper: THE STRING TO END ALL STRINGS!

See also

String manipulation
Locale
Interpretation of multibyte-character sequences
_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l