_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l

Article
12/21/2012

Convert a string to uppercase, using the current locale or a specified locale passed in. These are versions of _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr with 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 with /ZW.

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 are not 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 versions of these functions first fill the buffer with 0xFD. To disable this behavior, use _CrtSetDebugFillThreshold.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _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 additional compatibility information, see Compatibility in the Introduction.

Example

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

.NET Framework Equivalent

System::String::ToUpper

Share via