_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l

Converts a string to uppercase, by using the current locale or a specified locale that's passed in. These versions of _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr have security enhancements, as described in Security features in the CRT.

Important

_mbsupr_s and _mbsupr_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 _strupr_s(
   char *str,
   size_t numberOfElements
);
errno_t _wcsupr_s(
   wchar_t * str,
   size_t numberOfElements
);
errno_t _strupr_s_l(
   char * str,
   size_t numberOfElements,
   _locale_t locale
);
errno_t _wcsupr_s_l(
   wchar_t * str,
   size_t numberOfElements,
   _locale_t locale
);
errno_t _mbsupr_s(
   unsigned char *str,
   size_t numberOfElements
);
errno_t _mbsupr_s_l(
   unsigned char *str,
   size_t numberOfElements,
   _locale_t locale
);
template <size_t size>
errno_t _strupr_s(
   char (&str)[size]
); // C++ only
template <size_t size>
errno_t _wcsupr_s(
   wchar_t (&str)[size]
); // C++ only
template <size_t size>
errno_t _strupr_s_l(
   char (&str)[size],
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _wcsupr_s_l(
   wchar_t (&str)[size],
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsupr_s(
   unsigned char (&str)[size]
); // C++ only
template <size_t size>
errno_t _mbsupr_s_l(
   unsigned char (&str)[size],
   _locale_t locale
); // C++ only

Parameters

str
String to capitalize.

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 is a NULL pointer, 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 return ERANGE and set errno to ERANGE.

Remarks

The _strupr_s function converts, in place, each lowercase letter in str to uppercase. _wcsupr_s is the wide-character version of _strupr_s. _mbsupr_s is the multi-byte character version of _strupr_s.

The conversion is determined by the LC_CTYPE category setting of the locale. Other characters aren't affected. For more information on LC_CTYPE, see setlocale. The versions of these functions without the _l suffix use the current locale; the visions with the _l suffix are identical except that they use the locale 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
_tcsupr_s	_strupr_s	_mbsupr_s	_wcsupr_s
_tcsupr_s_l	_strupr_s_l	_mbsupr_s_l	_wcsupr_s_l

Requirements

Routine	Required header
_strupr_s, _strupr_s_l	<string.h>
_wcsupr_s, _wcsupr_s_l, _mbsupr_s, _mbsupr_s_l	<string.h> or <wchar.h>

For more compatibility information, see Compatibility.

Example

See the example for _strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l .

See also

Locale
Interpretation of multibyte-character sequences
String manipulation
_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l