_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l

Initialize characters of a string to a given character. These are versions of _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l with security enhancements as described in Security Features in the CRT.

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 is not 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 does not 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; see setlocale for more information. 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 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

_tcsnset_s

_strnset_s

_mbsnbset_s

_wcsnset_s

_tcsnset_s_l

_strnset_s_l

_mbsnbset_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 additional compatibility information, see Compatibility in the Introduction.

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

.NET Framework Equivalent

System::String::Replace

See Also

Reference

String Manipulation (CRT)

Locale

Interpretation of Multibyte-Character Sequences

strcat, wcscat, _mbscat

strcmp, wcscmp, _mbscmp

strcpy, wcscpy, _mbscpy

_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l