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

Article
11/16/2012

Get the length of a string, using the current locale or one that has been passed in. More secure versions of strlen, strlen_l, wcslen, wcslen_l, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l.

size_t strnlen(
   const char *str,
   size_t numberOfElements 
);
size_t strnlen_s(
   const char *str,
   size_t numberOfElements 
);
size_t strnlen_l(
   const char *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_l(
   const wchar_t *str,
   size_t numberOfElements,
   _locale_t locale
);
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 (excluding the terminating null). 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 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 only intended to be used to calculate the size of incoming untrusted data in a buffer of known size (such as a network packet). strnlen will calculate the length but not walk past the end of your 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_l interpret the string as a single-byte character string, so its return value is always equal to the number of bytes, even if the string contains multibyte characters. wcsnlen and wcsnlen_l are wide-character versions of strnlen and strnlen_l respectively; the arguments for wcsnlen and wcsnlen_l are wide-character strings and the count of characters are in wide character units. wcsnlen, wcsnlen_l, strnlen and strnlen_l otherwise behave identically.

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

strnlen_s and wcsnlen_s validate their parameters. If str is NULL, the functions will 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_l	_mbsnlen_l	wcsnlen_l

_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 currently in use or the locale passed in; it does not test for multibyte-character validity. _mbstrnlen tests for multibyte-character validity and recognizes multibyte-character sequences. If the string 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 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.

Requirements

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

For additional compatibility information, see Compatibility in the Introduction.

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