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_lwcsncat、_wcsncat_l、、_mbsncat、_mbsncat_l
strncmp、 、 wcsncmp、 _mbsncmp_mbsncmp_l
strcoll 函數
strncpy_s、、_strncpy_s_lwcsncpy_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