strnlen
, strnlen_s
, wcsnlen
, wcsnlen_s
, _mbsnlen
, _mbsnlen_l
, _mbstrnlen
, _mbstrnlen_l
使用目前的地區設定或是已傳入的地區設定取得字串的長度。 這些函式是更安全的 、、 wcslen
、 _mbslen
、 _mbslen_l
、 _mbstrlen
、 _mbstrlen_l
。 strlen
重要
_mbsnlen
、 _mbsnlen_l
、 _mbstrnlen
和 _mbstrnlen_l
不能用於在 Windows 執行階段 中執行的應用程式。 如需詳細資訊,請參閱 CRT functions not supported in Universal Windows Platform apps (通用 Windows 平台應用程式中不支援的 CRT 函式)。
語法
size_t strnlen(
const char *str,
size_t numberOfElements
);
size_t strnlen_s(
const char *str,
size_t numberOfElements
);
size_t wcsnlen(
const wchar_t *str,
size_t numberOfElements
);
size_t wcsnlen_s(
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 中的全域狀態。
泛型文字常式對應
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。
需求
常式 | 必要的標頭 |
---|---|
strnlen , strnlen_s |
<string.h> |
wcsnlen , wcsnlen_s |
<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);
}
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
另請參閱
字串操作
地區設定
多位元組字元序列的解譯
setlocale
, _wsetlocale
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
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應