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

現在のロケールまたは渡されたロケールを使用して、文字列の長さを取得します。 これらの関数は、 strlen、 wcslen、 _mbslen、 _mbslen_l、 _mbstrlen、 _mbstrlen_lのより安全なバージョンです。

重要

_mbsnlen、_mbsnlen_l、_mbstrnlen、および_mbstrnlen_lは、Windows ランタイムで実行されるアプリケーションでは使用できません。 詳細については、「ユニバーサル 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 バイト (または wcsnlenのワイド文字) 内に null ターミネータがない場合は、エラー状態を示すために numberOfElements が返されます。null で終わる文字列の長さは厳密に numberOfElements未満です。

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

解説

Note

strnlen は strlen に代わるものではありません。strnlen は、既知のサイズのバッファー (ネットワーク パケットなど) 内の受信した信頼できないデータのサイズを計算するためにのみ使用することを目的としています。 strnlen は長さを計算しますが、文字列に終端文字がない場合にバッファーの末尾を超えません。 その他の状況では、strlen を使用します。 (同じことが wcsnlen、_mbsnlen、および _mbstrnlen に適用されます)。

これらの各関数は、str 内の文字数を返します (終端の null 文字は含まれません)。 ただし、strnlen および strnlen_s は文字列を 1 バイト文字列として扱うため、マルチバイト文字が含まれている場合でも、戻り値は常にバイト数と同じです。 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>

互換性の詳細については、「 Compatibility」を参照してください。

例

// 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