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

發行項
03/26/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 會傳回表示錯誤條件;innull 結尾字串有明顯小於 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);
}