strnlen、strnlen_s、wcsnlen、wcsnlen_s、_mbsnlen、_mbsnlen_l、_mbstrnlen、_mbstrnlen_l

發行項
06/09/2015

使用目前的地區設定或是已傳入的地區設定取得字串的長度。這些是較安全版的 strlen、wcslen、_mbslen、_mbslen_l、_mbstrlen、_mbstrlen_l。

重要

在 Windows 執行階段中執行的應用程式中無法使用 _mbsnlen、_mbsnlen_l、_mbstrnlen 和 _mbstrnlen_l。如需詳細資訊，請參閱 /ZW 不支援 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。

一般文字常式對應

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、_wsetlocale。這些函式的版本均相同，除了沒有 _l 後置字元的函式會針對此地區設定的相關行為使用目前的地區設定，而具有 _l 後置字元的函式會改用傳入的地區設定參數。如需詳細資訊，請參閱地區設定。

需求

常式	必要的標頭
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);
}