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

项目
04/10/2013

获取字符串的长度通过使用传递的当前区域设置或一个。这些是 strlen， strlen_l， wcslen， wcslen_l， _mbslen， _mbslen_l， _mbstrlen， _mbstrlen_l的更安全版本。

重要

_mbsnlen、_mbsnlen_l、_mbstrnlen和 _mbstrnlen_l 不能在 Windows 运行时执行的应用程序。有关更多信息，请参见 CRT 函数不支持与 /ZW。

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
);

参数

str
null 终止的字符串。
numberOfElements
字符串缓冲区的大小。
locale
使用的区域设置。

返回值

这些函数返回的字符数。该字符串，不包括终止 null 字符)。如果在该字符串 (或 wcsnlen的宽字符) 的第一个 numberOfElements 字节内 null 结束符，则 numberOfElements 返回一个错误状态；null 终止的字符串大于 numberOfElements严格小于的长度。

如果该字符串包含无效的多字节字符，_mbstrnlen 和 _mbstrnlen_l 返回 -1。

备注

strnlen 不是 strlen的替换；strnlen 只应用于计算传入不信任的数据的大小缓冲区中的已知大小 (例如，网络数据包。如果该字符串未终止，strnlen 计算该长度，但不遍历缓冲区末尾的。对于其他情况，请使用 strlen。(同样适用于 wcsnlen、_mbsnlen和 _mbstrnlen。)

这些函数都返回一个字符数。str，不包括终止 null 字符)。但是，strnlen 和 strnlen_l 解释字符串作为单字节字符字符串，并返回值与字节数总是相同的，因此，即使该字符串包含一个多字节字符。 wcsnlen 和 wcsnlen_l 分别为 strnlen 和 strnlen_l 的宽字符版本；wcsnlen 和 wcsnlen_l 的参数是宽字符字符串，以及计算字符在宽字符单元。否则，wcsnlen、wcsnlen_l、strnlen 和 strnlen_l 具有相同的行为。

strnlen、wcsnlen, 和 _mbsnlen 不验证方法的参数。如果 str 是 NULL，发生访问冲突。

strnlen_s 和 wcsnlen_s 验证其参数。如果 str 是 NULL，函数返回 0。

_mbstrnlen 来验证其参数。如果 str 是 NULL，或者，如果 numberOfElements 比 INT_MAX大，_mbstrnlen 生成无效的参数异常，如参数验证所述。如果执行允许继续，_mbstrnlen 设置 errno 到 EINVAL 并返回 -1。

一般文本例程映射

TCHAR.H 实例	未定义的_UNICODE & _MBCS	定义的_MBCS	定义的_UNICODE
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen_l	_mbsnlen_l	wcsnlen_l

_mbsnlen 和 _mbstrnlen 返回多字节字符数在多字节字符字符串的。 _mbsnlen 识别多字节字符顺序基于当前正在使用的多字节代码页或根据传入的区域设置；它不测试多字节字符的有效性。 _mbstrnlen 测试多字节字符有效性并识别多字节字符序列。如果传递到 _mbstrnlen 的字符串包含无效的多字节字符，errno 设置为 EILSEQ。

输出值受设置 LC_CTYPE 类设置的影响区域设置；请参见 setlocale， _wsetlocale 有关更多信息。这些功能的版本相同，不同之处在于，没有 _l 后缀使用此区域设置相关的行为的当前区域设置和版本有 _l 后缀使用区域设置参数传递的脚本。有关更多信息，请参见区域设置。

要求

实例	必需的标头
strnlen, strnlen_s, strnlen_l	<string.h>
wcsnlen, wcsnlen_s, wcsnlen_l	<string.h> 或 <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

有关其他的兼容性信息，请参见兼容性。

示例

// 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);
}