Get the length of a string, using the current locale or a specified locale. More secure versions of these functions are available; see strnlen, strnlen_l, wcsnlen, wcsnlen_l, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l
size_t strlen(
const char *str
);
size_t strlen_l(
const char *str,
_locale_t locale
);
size_t wcslen(
const wchar_t *str
);
size_t wcslen_l(
const wchar_t *str,
_locale_t locale
);
size_t _mbslen(
const unsigned char *str
);
size_t _mbslen_l(
const unsigned char *str,
_locale_t locale
);
size_t _mbstrlen(
const char *str
);
size_t _mbstrlen_l(
const char *str,
_locale_t locale
);
Parameters
- str
-
Null-terminated string.
- locale
-
Locale to use.
Each of these functions returns the number of characters in str, excluding the terminal NULL. No return value is reserved to indicate an error, except for _mbstrlen, which returns -1 if the string contains an invalid multibyte character.
However, strlen interprets 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. wcslen is a wide-character version of strlen; the argument of wcslen is a wide-character string and the count of characters is in wide (two-byte) characters. wcslen and strlen behave identically otherwise.
Security Note These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see Avoiding Buffer Overruns.
Generic-Text Routine Mappings
TCHAR.H routine |
_UNICODE & _MBCS not defined |
_MBCS defined |
_UNICODE defined |
_tcslen
|
strlen
|
strlen
|
wcslen
|
_tcsclen
|
strlen
|
_mbslen
|
wcslen
|
_tcsclen_l
|
strlen_l
|
_mbslen_l
|
wcslen_l
|
_mbslen,_mbslen_l, _mbstrlenand_mbstrlen_l return the number of multibyte characters in a multibyte-character string but they do not test for multibyte-character validity. _mbstrlenand_mbstrlen_l tests for multibyte-character validity and recognizes multibyte-character sequencessetlocale, _wsetlocale. If the string passed to _mbstrlen or_mbstrlen_l contain an invalid multibyte character for the code page, it returns -1 and sets errno 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.
Routine |
Required header |
Compatibility |
strlen
|
<string.h>
|
ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
|
strlen_l
|
<string.h>
|
Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
|
wcslen, wcslen_l
|
<string.h> or <wchar.h>
|
ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
|
_mbslen, _mbslen_l
|
<mbstring.h>
|
Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
|
_mbstrlen, _mbstrlen_l
|
<stdlib.h>
|
Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
|
For additional compatibility information, see Compatibility in the Introduction.
// crt_strlen.c
// Determine the length of a string. For the multi-byte character
// example to work correctly, the Japanese language support for
// non-Unicode programs must be enabled by the operating system.
#include <string.h>
#include <locale.h>
int main()
{
char* str1 = "Count.";
wchar_t* wstr1 = L"Count.";
char * mbstr1;
char * locale_string;
// strlen gives the length of single-byte character string
printf("Length of '%s' : %d\n", str1, strlen(str1) );
// wstrlen gives the length of a wide character string
wprintf(L"Length of '%s' : %d\n", wstr1, wcslen(wstr1) );
// A multibyte string: [A] [B] [C] [katakana A] [D] [\0]
// in Code Page 932. For this example to work correctly,
// the Japanese language support must be enabled by the
// operating system.
mbstr1 = "ABC" "\x83\x40" "D";
locale_string = setlocale(LC_CTYPE, "Japanese_Japan");
if (locale_string == NULL)
{
printf("Japanese locale not enabled. Exiting.\n");
exit(1);
}
else
{
printf("Locale set to %s\n", locale_string);
}
// _mbslen will recognize the Japanese multibyte character if the
// current locale used by the operating system is Japanese
printf("Length of '%s' : %d\n", mbstr1, _mbslen(mbstr1) );
// _mbstrlen will recognize the Japanese multibyte character
// since the CRT locale is set to Japanese even if the OS locale
// isnot.
printf("Length of '%s' : %d\n", mbstr1, _mbstrlen(mbstr1) );
printf("Bytes in '%s' : %d\n", mbstr1, strlen(mbstr1) );
}
Sample Output
Length of 'Count.' : 6
Length of 'Count.' : 6
Length of 'ABCァD' : 5
Length of 'ABCァD' : 5
Bytes in 'ABCァD' : 6
.NET Framework Equivalent