strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l

Article
06/05/2017

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 strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l.

Gets the length of a string by using the current locale or one that has been passed in. These are more secure versions of strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

Important

_mbsnlen, _mbsnlen_l, _mbstrnlen, and _mbstrnlen_l cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

Syntax

size_t strnlen(  
   const char *str,  
   size_t numberOfElements   
);  
size_t strnlen_s(  
   const char *str,  
   size_t numberOfElements   
);  
size_t wcsnlen(  
   const wchar_t *str,  
   size_t numberOfElements  
);  
size_t wcsnlen_s(  
   const wchar_t *str,  
   size_t numberOfElements  
);  
size_t _mbsnlen(  
   const unsigned char *str,  
   size_t numberOfElements  
);  
size_t _mbsnlen_l(  
   const unsigned char *str,  
   size_t numberOfElements,  
   _locale_t locale  
);  
size_t _mbstrnlen(  
   const char *str,  
   size_t numberOfElements  
);  
size_t _mbstrnlen_l(  
   const char *str,  
   size_t numberOfElements,  
   _locale_t locale  
);

Parameters

str
Null-terminated string.

numberOfElements
The size of the string buffer.

locale
Locale to use.

Return Value

These functions return the number of characters in the string, not including the terminating null character. If there is no null terminator within the first numberOfElements bytes of the string (or wide characters for wcsnlen), then numberOfElements is returned to indicate the error condition; null-terminated strings have lengths that are strictly less than numberOfElements.

_mbstrnlen and _mbstrnlen_l return -1 if the string contains an invalid multibyte character.

Remarks

Note

strnlen is not a replacement for strlen; strnlen is intended to be used only to calculate the size of incoming untrusted data in a buffer of known size—for example, a network packet. strnlen calculates the length but doesn't walk past the end of the buffer if the string is unterminated. For other situations, use strlen. (The same applies to wcsnlen, _mbsnlen, and _mbstrnlen.)

Each of these functions returns the number of characters in str, not including the terminating null character. However, strnlen and strnlen_s interpret the string as a single-byte character string and therefore, the return value is always equal to the number of bytes, even if the string contains multibyte characters. wcsnlen and wcsnlen_s are wide-character versions of strnlen and strnlen_s respectively; the arguments for wcsnlen and wcsnlen_s are wide-character strings and the count of characters are in wide-character units. Otherwise, wcsnlen and strnlen behave identically, as do strnlen_s and wcsnlen_s.

strnlen, wcsnlen, and _mbsnlen do not validate their parameters. If str is NULL, an access violation occurs.

strnlen_s and wcsnlen_s validate their parameters. If str is NULL, the functions return 0.

_mbstrnlen also validates its parameters. If str is NULL, or if numberOfElements is greater than INT_MAX, _mbstrnlen generates an invalid parameter exception, as described in Parameter Validation. If execution is allowed to continue, _mbstrnlen sets errno to EINVAL and returns -1.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
`_tcsnlen`	`strnlen`	`strnlen`	`wcsnlen`
`_tcscnlen`	`strnlen`	`_mbsnlen`	`wcsnlen`
`_tcscnlen_l`	`strnlen`	`_mbsnlen_l`	`wcsnlen`

_mbsnlen and _mbstrnlen return the number of multibyte characters in a multibyte-character string. _mbsnlen recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it does not test for multibyte-character validity. _mbstrnlen tests for multibyte-character validity and recognizes multibyte-character sequences. If the string that's passed to _mbstrnlen contains an invalid multibyte character, errno is set to EILSEQ.

The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale, _wsetlocale for more information. The versions of these functions are identical, except that the ones that don't have the _l suffix use the current locale for this locale-dependent behavior and the versions that have the _l suffix instead use the locale parameter that's passed in. For more information, see Locale.

Requirements

Routine	Required header
`strnlen`, `strnlen_s`	<string.h>
`wcsnlen`, `wcsnlen_s`	<string.h> or <wchar.h>
`_mbsnlen`, `_mbsnlen_l`	<mbstring.h>
`_mbstrnlen`, `_mbstrnlen_l`	<stdlib.h>

For additional compatibility information, see Compatibility.

Example

  
      // crt_strnlen.c  
  
#include <string.h>  
  
int main()  
{  
   // str1 is 82 characters long. str2 is 159 characters long   
  
   char* str1 = "The length of a string is the number of characters\n"  
               "excluding the terminating null.";  
   char* str2 = "strnlen takes a maximum size. If the string is longer\n"  
                "than the maximum size specified, the maximum size is\n"  
                "returned rather than the actual size of the string.";  
   size_t len;  
   size_t maxsize = 100;  
  
   len = strnlen(str1, maxsize);  
   printf("%s\n Length: %d \n\n", str1, len);  
  
   len = strnlen(str2, maxsize);  
   printf("%s\n Length: %d \n", str2, len);  
}

The length of a string is the number of characters  
excluding the terminating null.  
 Length: 82   
  
strnlen takes a maximum size. If the string is longer  
than the maximum size specified, the maximum size is  
returned rather than the actual size of the string.  
 Length: 100

.NET Framework Equivalent

System::String::Length

Share via