strtok、_strtok_l、wcstok、_wcstok_l、_mbstok、_mbstok_l

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

現在のロケールまたは渡されたロケールを使用して、文字列内の次のトークンを見つけます。これらの関数のセキュリティが強化されたバージョンについては「strtok_s、_strtok_s_l、wcstok_s、_wcstok_s_l、_mbstok_s、_mbstok_s_l」を参照してください。

char *strtok(
   char *strToken,
   const char *strDelimit 
);
wchar_t *wcstok(
   wchar_t *strToken,
   const wchar_t *strDelimit 
);
unsigned char *_mbstok(
   unsigned char*strToken,
   const unsigned char *strDelimit 
);
unsigned char *_mbstok(
   unsigned char*strToken,
   const unsigned char *strDelimit,
   _locale_t locale
);

パラメータ

strToken
1 つ以上のトークンを含む文字列。
strDelimit
区切り文字のセット。
locale
使用するロケール。

戻り値

strToken で見つかった次のトークンへのポインタを返します。それ以上トークンが見つからない場合は、NULL を返します。呼び出しのたびに、返されたトークンの後に出現する最初の区切り記号を NULL 文字に置換することによって、strToken が変更されます。

解説

strtok 関数は、strToken で次のトークンを検索します。strDelimit 内の文字セットは、現在の呼び出しの strToken で見つかる可能性のあるトークンの区切り文字を指定します。wcstok 関数と _mbstok 関数は、strtok 関数のワイド文字バージョンとマルチバイト文字バージョンです。wcstok 関数の引数と戻り値はワイド文字列で、_mbstok 関数の引数と戻り値はマルチバイト文字列です。それ以外では、これらの関数の動作は同じです。

セキュリティに関するメモ :
これらの関数は、バッファオーバーランが原因で発生する可能性のある問題の影響を受けます。バッファオーバーランは、システムを攻撃するときによく使用される方法であり、その結果、認められていない権限が昇格されます。詳細については、「Avoiding Buffer Overruns」を参照してください。

strtok 関数は、最初の呼び出し時には先頭の区切り文字を読み飛ばし、strToken 内で見つかった最初のトークンの終端に null 文字を追加し、このトークンへのポインタを返します。strtok 関数を続けて呼び出すことによって、strToken の残りの部分からトークンをさらに取り出すことができます。strtok 関数を呼び出すたびに、その呼び出しで返された token の後に null 文字が挿入され、strToken が変更されます。strToken から次のトークンを読み込むには、strToken 引数を NULL 値にして strtok を呼び出します。NULL strToken 引数により、strtok 関数は、変更された strToken で次のトークンを検索します。区切り文字のセットを変更できるように、引数 strDelimit には呼び出しごとに任意の値を指定できます。

出力値は、ロケールの LC_CTYPE カテゴリの設定で決まります。詳細については、「setlocale」を参照してください。_l サフィックスが付いていないこの関数のバージョンでは、このロケールに依存する動作に現在のロケールを使用します。_l サフィックスが付いているバージョンは、渡されたロケールパラメータを代わりに使用する点を除いて同じです。詳細については、「ロケール」を参照してください。

メモ :
各関数は、スレッドのローカルの静的変数を使用して、文字列からトークンを取り出します。このため、複数のスレッドでこれらの関数を同時に呼び出しても、問題が発生することはありません。しかし、単一のスレッドでこれらの関数のうちいずれかに対する呼び出しをインターリーブすると、データが破損して正確な結果を取得できない可能性が高くなります。複数の文字列を解析するときは、1 つの文字列の解析が終了してから次に進むようにします。また、これらの関数のうちいずれかをループ内から呼び出す場合、同じループで別の関数を呼び出すと、問題が発生する可能性があります。別の関数でこれらの関数のうちいずれかが使用されることになった場合、呼び出しシーケンスがインターリーブされて、データが破損する可能性があります。

各関数は、スレッドのローカルの静的変数を使用して、文字列からトークンを取り出します。このため、複数のスレッドでこれらの関数を同時に呼び出しても、問題が発生することはありません。しかし、単一のスレッドでこれらの関数のうちいずれかに対する呼び出しをインターリーブすると、データが破損して正確な結果を取得できない可能性が高くなります。複数の文字列を解析するときは、1 つの文字列の解析が終了してから次に進むようにします。また、これらの関数のうちいずれかをループ内から呼び出す場合、同じループで別の関数を呼び出すと、問題が発生する可能性があります。別の関数でこれらの関数のうちいずれかが使用されることになった場合、呼び出しシーケンスがインターリーブされて、データが破損する可能性があります。

汎用テキストルーチンのマップ

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tcstok	strtok	_mbstok	wcstok
_tcstok	_strtok_l	_mbstok_l	_wcstok_l

必要条件

ルーチン	必須ヘッダー
strtok	<string.h>
wcstok	<string.h> または <wchar.h>
_mbstok, _mbstok_l	<mbstring.h>

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

使用例

// crt_strtok.c
// compile with: /W3
// In this program, a loop uses strtok
// to print all the tokens (separated by commas
// or blanks) in the string named "string".
//
#include <string.h>
#include <stdio.h>

char string[] = "A string\tof ,,tokens\nand some  more tokens";
char seps[]   = " ,\t\n";
char *token;

int main( void )
{
   printf( "Tokens:\n" );
 
   // Establish string and get the first token:
   token = strtok( string, seps ); // C4996
   // Note: strtok is deprecated; consider using strtok_s instead
   while( token != NULL )
   {
      // While there are tokens in "string"
      printf( " %s\n", token );

      // Get next token: 
      token = strtok( NULL, seps ); // C4996
   }
}

Tokens:
 A
 string
 of
 tokens
 and
 some
 more
 tokens