strlen, strnlen_s

 

C

Language

headers

Type support

Dynamic memory management

Error handling

Program utilities

Variadic function support

Date and time utilities

Strings library

Algorithms

Numerics

Input/output support

Localization support

Thread support (C11)

Atomic operations (C11)

Technical Specifications

 

Strings library

Byte strings

Multibyte strings

Wide strings

 

Null-terminated byte strings

Functions
Character manipulation
isalnum isalpha islower isupper isdigit isxdigit isblank (C99)	iscntrl isgraph isspace isprint ispunct tolower toupper
Conversions to numeric formats
atof atoiatolatoll strtolstrtoll	strtoulstrtoull strtofstrtodstrtold strtoimaxstrtoumax (C99)(C99)
String manipulation
strcpystrcpy_s (C11)
strncpystrncpy_s (C11)
strcatstrcat_s (C11)
strncatstrncat_s (C11)
strxfrm
String examination
strlenstrnlen_s (C11) strcmp strncmp strcoll strchr strrchr	strspn strcspn strpbrk strstr strtokstrtok_s (C11)
Memory manipulation
memchr
memcmp
memsetmemset_s (C11)
memcpymemcpy_s (C11)
memmovememmove_s (C11)
Miscellaneous
strerrorstrerror_sstrerrorlen_s (C11)(C11)

 

Defined in header <string.h>
size_t strlen( const char *str );	(1)
size_t strnlen_s( const char *str, size_t strsz );	(2)	(since C11)

1) Returns the length of the given null-terminated byte string, that is, the number of characters in a character array whose first element is pointed to by str up to and not including the first null character.

The behavior is undefined if str is not a pointer to a null-terminated byte string.

2) Same as (1), except that the function returns zero if str is a null pointer and returns strsz if the null character was not found in the first strsz bytes of str.

The behavior is undefined if both str points to a character array which lacks the null character and the size of that character array < strsz; in other words, an erroneous value of strsz does not expose the impending buffer overflow.

As with all bounds-checked functions, strnlen_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including string.h.

Parameters

str	-	pointer to the null-terminated byte string to be examined
strsz	-	maximum number of characters to examine

Return value

1) The length of the null-terminated byte string str.

2) The length of the null-terminated byte string str on success, zero if str is a null pointer, strsz if the null character was not found.

Notes

strnlen_s and wcsnlen_s are the only bounds-checked functions that do not invoke the runtime constraints handler. They are pure utility functions used to provide limited support for non-null terminated strings.

Example

Run this code

#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
#include <stdio.h>
 
int main(void)
{
    const char str[] = "How many characters does this string contain?";
 
    printf("without null character: %zu\n", strlen(str));
    printf("with null character:    %zu\n", sizeof str);
 
#ifdef __STDC_LIB_EXT1__
    printf("without null character: %zu\n", strnlen_s(str, sizeof str));
#endif
}

Output:

without null character: 45
with null character:    46
without null character: 45

References

• C11 standard (ISO/IEC 9899:2011):

• 7.24.6.3 The strlen function (p: 372)

• K.3.7.4.4 The strnlen_s function (p: 623)

• C99 standard (ISO/IEC 9899:1999):

• 7.21.6.3 The strlen function (p: 334)

• C89/C90 standard (ISO/IEC 9899:1990):

• 4.11.6.3 The strlen function

See also

wcslenwcsnlen_s (C95)(C11)	returns the length of a wide string (function)
mblen	returns the number of bytes in the next multibyte character (function)
C++ documentation for strlen