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

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

See Also

Reference

String Manipulation (CRT)

Locale

Interpretation of Multibyte-Character Sequences

setlocale, _wsetlocale

strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l

strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

strcoll Functions

strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

strrchr, wcsrchr, _mbsrchr, _mbsrchr_l

_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l

strspn, wcsspn, _mbsspn, _mbsspn_l