strtok_s、_strtok_s_l、wcstok_s、_wcstok_s_l、_mbstok_s、_mbstok_s_l

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

現在のロケールまたは渡されたロケールを使用して、文字列から次のトークンを見つけます。これらの関数は、「CRT のセキュリティ機能」に説明されているように、strtok、_strtok_l、wcstok、_wcstok_l、_mbstok、_mbstok_l のセキュリティが強化されたバージョンです。

char *strtok_s(
   char *strToken,
   const char *strDelimit,
   char **context
);
char *_strtok_s_l(
   char *strToken,
   const char *strDelimit,
   char **context,
   _locale_t locale
);
wchar_t *wcstok_s(
   wchar_t *strToken,
   const wchar_t *strDelimit, 
   wchar_t **context
);
wchar_t *_wcstok_s_l(
   wchar_t *strToken,
   const wchar_t *strDelimit, 
   wchar_t **context,
   _locale_t locale
);
unsigned char *_mbstok_s(
   unsigned char*strToken,
   const unsigned char *strDelimit, 
   char **context
);
unsigned char *_mbstok_s(
   unsigned char*strToken,
   const unsigned char *strDelimit, 
   char **context,
   _locale_t locale
);

パラメーター

strToken
1 つ以上のトークンを含む文字列。
strDelimit
区切り文字のセット。
context
strtok_s の呼び出し間の位置情報を格納します。
locale
使用するロケール。

戻り値

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

エラー条件

strToken	strDelimit	context	戻り値	errno
NULL	any	null ポインターへのポインター	NULL	EINVAL
any	NULL	any	NULL	EINVAL
any	any	NULL	NULL	EINVAL

strToken が NULL であっても、コンテキストが有効なコンテキストポインターを指すポインターである場合、エラーにはなりません。

解説

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

この関数は、パラメーターを検証します。「エラー条件」に示されているエラー条件が発生した場合は、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、NULL を返します。

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

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

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

context パラメーターは strtok と _strtok_l で使用される静的なバッファーより優先されるため、同じスレッド内で同時に 2 つの文字列を解析することもできます。

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

必要条件

ルーチン	必須ヘッダー
strtok_s	<string.h>
_strtok_s_l	<string.h>
wcstok_s, _wcstok_s_l	<string.h> または <wchar.h>
_mbstok_s, _mbstok_s_l	<mbstring.h>

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

使用例

// crt_strtok_s.c
// In this program, a loop uses strtok_s
// to print all the tokens (separated by commas
// or blanks) in two strings at the same time.
//

#include <string.h>
#include <stdio.h>

char string1[] =
    "A string\tof ,,tokens\nand some  more tokens";
char string2[] =
    "Another string\n\tparsed at the same time.";
char seps[]   = " ,\t\n";
char *token1 = NULL;
char *token2 = NULL;
char *next_token1 = NULL;
char *next_token2 = NULL;

int main( void )
{
    printf( "Tokens:\n" );

    // Establish string and get the first token:
    token1 = strtok_s( string1, seps, &next_token1);
    token2 = strtok_s ( string2, seps, &next_token2);

    // While there are tokens in "string1" or "string2"
    while ((token1 != NULL) || (token2 != NULL))
    {
        // Get next token:
        if (token1 != NULL)
        {
            printf( " %s\n", token1 );
            token1 = strtok_s( NULL, seps, &next_token1);
        }
        if (token2 != NULL)
        {
            printf("        %s\n", token2 );
            token2 = strtok_s (NULL, seps, &next_token2);
        }
    }
}