使用当前区域设置或已传入的一个区域设置获取字符串的长度。 这些函数是 strlen、wcslen、_mbslen、_mbslen_l、_mbstrlen 和 _mbstrlen_l 的更安全的版本。
重要
_mbsnlen、_mbsnlen_l、_mbstrnlen 和 _mbstrnlen_l 无法用于在 Windows 运行时中执行的应用程序。 有关详细信息，请参阅通用 Windows 平台应用中不支持的 CRT 函数。
语法
size_t strnlen(
const char *str,
size_t numberOfElements
);
size_t strnlen_s( // See note in remarks section about linkage
const char *str,
size_t numberOfElements
);
size_t wcsnlen(
const wchar_t *str,
size_t numberOfElements
);
size_t wcsnlen_s( // See note in remarks section about linkage
const wchar_t *str,
size_t numberOfElements
);
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 结尾的字符。 如果字符串的第一个 numberOfElements 字节中不包含 null 终止符（或 wcsnlen 的宽字符），则返回 numberOfElements 以指示错误条件；以 null 结尾的字符串的长度严格小于 numberOfElements。
如果字符串包含无效的多字节字符，则 _mbstrnlen 和 _mbstrnlen_l 将返回 -1。
备注
注意
strnlen 不是 strlen 的替代方法；应将 strnlen 仅用于计算已知大小的缓冲区中传入的不受信任数据的大小，例如网络数据包。
strnlen 计算长度，但是如果该字符串是非终止的，则它不会超过缓冲区的末尾。 对于其他情况，请使用 strlen。 （同一情况适用于 wcsnlen、_mbsnlen 和 _mbstrnlen。）
其中每个函数都将返回 str 中的字符数，不包括以 null 结尾的字符。 但是，strnlen 和 strnlen_s 会将字符串解释为单字节字符字符串，因此即使该字符串包含多字节字符，返回值也始终等于字节数。
wcsnlen 和 wcsnlen_s 分别是 strnlen 和 strnlen_s 的宽字符版本；wcsnlen 和 wcsnlen_s 的参数是宽字符字符串且字符计数以宽字符为单位。 除此以外，wcsnlen 和 strnlen 的行为完全相同，strnlen_s 和 wcsnlen_s 也是如此。
strnlen、wcsnlen 和 _mbsnlen 不会验证其参数。 如果 str 是 NULL，则会发生访问冲突。
strnlen_s 和 wcsnlen_s 将验证其参数。 如果 str 是 NULL，则函数返回 0。
_mbstrnlen 也会验证其参数。 如果 str 为 NULL，或者如果 numberOfElements 大于 INT_MAX，则 _mbstrnlen 将生成无效的参数异常，如参数验证中所述。 如果允许执行继续，则 _mbstrnlen 会将 errno 设置为 EINVAL 并返回 -1。
默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。
注意
使用 Windows SDK 版本 10.0.26100.6901 和 Visual Studio 2026 或更高版本时， strnlen_swcsnlen_s 不再 static inline （内部链接）。 相反，它们是 inline （外部链接）。
若要返回到以前的行为， #define _STATIC_INLINE_UCRT_FUNCTIONS=1 请先包括任何 CRT 标头。 默认情况下，_STATIC_INLINE_UCRT_FUNCTIONS 设置为 0。
此更改增加了与 C++ 标准的 UCRT 一致性，并提高了与C++模块的兼容性。
一般文本例程映射
TCHAR.H 例程 |
_UNICODE 和 _MBCS 未定义 |
_MBCS 已定义 |
_UNICODE 已定义 |
|---|---|---|---|
_tcsnlen |
strnlen |
strnlen |
wcsnlen |
_tcscnlen |
strnlen |
_mbsnlen |
wcsnlen |
_tcscnlen_l |
strnlen |
_mbsnlen_l |
wcsnlen |
_mbsnlen 和 _mbstrnlen 以多字节字符字符串格式返回多字节字符的数量。
_mbsnlen 根据当前正在使用的多字节代码页或已传入的区域设置来识别多字节字符序列；它不会测试多字节字符的有效性。
_mbstrnlen 将测试多字节字符的有效性并识别多字节字符序列。 如果传递给 _mbstrnlen 的字符串包含无效的多字节字符，则 errno 将设置为 EILSEQ。
输出值受区域设置的 LC_CTYPE 类别设置的影响。 有关详细信息，请参阅 setlocale。 这些函数的版本相同，差异在于不包含 _l 后缀的版本使用与此区域设置相关的行为的当前区域设置，而包含 _l 后缀的版本则使用传入的区域设置参数。 有关详细信息，请参阅 Locale。
要求
| 例程 | 必需的标头 |
|---|---|
| %> | <string.h> |
| %> |
<string.h> 或 <wchar.h> |
| %> | <mbstring.h> |
| %> | <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);
}
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
另请参阅
字符串操作
区域设置
多字节字符序列的解释
%>
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strcoll 函数
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