_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _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.

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 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

Requirements

For additional compatibility information, see Compatibility.

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

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