_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l, _tcsnset_s, _tcsncset_s, _tcsncset_s_l

Initializes characters of a string to a given character. These versions of _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l have security enhancements, as described in Security features in the CRT.

Important

_mbsnset_s and _mbsnset_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.

For _tcsnset_s, _tcsnset_s_l, _tcsncset_s, and _tcsncset_s_l see Generic-text function mappings.

Syntax

errno_t _strnset_s(
   char *str,
   size_t numberOfElements,
   int c,
   size_t count
);
errno_t _strnset_s_l(
   char *str,
   size_t numberOfElements,
   int c,
   size_t count,
   _locale_t locale
);
errno_t _wcsnset_s(
   wchar_t *str,
   size_t numberOfElements,
   wchar_t c,
   size_t count
);
errno_t _wcsnset_s_l(
   wchar_t *str,
   size_t numberOfElements,
   wchar_t c,
   size_t count,
   _locale_t locale
);
errno_t _mbsnset_s(
   unsigned char *str,
   size_t numberOfElements,
   unsigned int c,
   size_t count
);
errno_t _mbsnset_s_l(
   unsigned char *str,
   size_t numberOfElements,
   unsigned int c,
   size_t count,
   _locale_t locale
);

Parameters

str
String to be altered.

numberOfElements
The size of the str buffer.

c
Character setting.

count
Number of characters to be set.

locale
Locale to use.

Return value

Zero if successful, otherwise an error code.

These functions validate their arguments. If str isn't a valid null-terminated string or the size argument is less than or equal to 0, then the invalid parameter handler is invoked, as described in Parameter validation. If execution is allowed to continue, these functions return an error code and set errno to that error code. The default error code is EINVAL if a more specific value doesn't apply.

Remarks

These functions set, at most, the first count characters of str to c. If count is greater than the size of str, the size of str is used instead of count. An error occurs if count is greater than numberOfElements and both those parameters are greater than the size of str.

_wcsnset_s and _mbsnset_s are wide-character and multibyte-character versions of _strnset_s. The string argument of _wcsnset_s is a wide-character string; that of _mbsnset_s is a multibyte-character string. These three functions behave identically otherwise.

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.

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

The function in the tchar.h column maps to the function in the other columns depending on the character set that is defined at compile time.

tchar.h function	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
_tcsnset_s	_strnset_s	_mbsnbset_s	_wcsnset_s
_tcsnset_s_l	_strnset_s_l	_mbsnbset_s_l	_wcsnset_s_l
_tcsncset_s	_strnset_s	_mbsnset_s	_wcsnset_s
_tcsncset_s_l	_strnset_s_l	_mbsnset_s_l	_wcsnset_s_l

Requirements

Routine	Required header
_strnset_s	<string.h>
_strnset_s_l	<tchar.h>
_wcsnset_s	<string.h> or <wchar.h>
_wcsnset_s_l	<tchar.h>
_mbsnset_s, _mbsnset_s_l	<mbstring.h>

For more compatibility information, see Compatibility.

Example

// crt_strnset_s.c
#include <string.h>
#include <stdio.h>

int main( void )
{
   char string[15] = "This is a test";
   /* Set not more than 4 characters of string to be *'s */
   printf( "Before: %s\n", string );
   _strnset_s( string, sizeof(string), '*', 4 );
   printf( "After:  %s\n", string );
}

Before: This is a test
After:  **** is a test

See also

String manipulation
Locale
Interpretation of multibyte-character sequences
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpy
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l