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

[アーティクル]
08/09/2011

現在のロケールまたは渡されたロケールを使用して文字列の長さを取得します。 strlen、strlen_l、wcslen、wcslen_l、_mbslen、_mbslen_l、_mbstrlen、_mbstrlen_l のセキュリティが強化されたバージョン。

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 文字を除いた文字列の文字数を返します。文字列の最初の numberOfElements バイト (wcsnlen の場合はワイド文字) 内に null 終端文字が存在しない場合は、null で終わる文字列の厳密な長さが、numberOfElements に満たないというエラー状況を示すために numberOfElements が返されます。

文字列に無効なマルチバイト文字が含まれる場合、_mbstrnlen と _mbstrnlen_l は -1 を返します。

解説

注意

strnlen を strlen の代わりに使用することはできません。strnlen は、ネットワークパケットなどの信頼できないソースから受け取る既知のサイズのバッファー内のデータを計算するためのみに使用します。 strnlen は、長さを計算しますが、文字列の終端がない場合、バッファーの末尾を越えません。それ以外の場合は、strlen を使用してください。同じことが、wcsnlen、_mbsnlen、および _mbstrnlen に適用されます。

これらの関数は、終端の null 文字を含まない str の文字数を返します。ただし、strnlen と strnlen_l は、文字列を 1 バイトの文字列として解釈するため、文字列にマルチバイト文字が含まれる場合でも、戻り値は常にバイト数と同じになります。 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」を参照してください。 _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>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// 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);
}