sscanf_s、_sscanf_s_l、swscanf_s、_swscanf_s_lsscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

文字列から書式付きデータを読み込みます。Reads formatted data from a string. これらのバージョンの sscanf、_sscanf_l、swscanf、_swscanf_l は、「CRT のセキュリティ機能」にあるとおり、セキュリティが強化されています。These versions of sscanf, _sscanf_l, swscanf, _swscanf_l have security enhancements, as described in Security Features in the CRT.

構文Syntax

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument ] ...
);

パラメーターParameters

バッファーbuffer
格納されるデータ。Stored data

formatformat
書式指定文字列。Format-control string. 詳細については、「Format Specification Fields: scanf and wscanf Functions」(scanf 関数と wscanf 関数の書式指定フィールド) をご覧ください。For more information, see Format Specification Fields: scanf and wscanf Functions.

argumentargument
省略可能な引数。Optional arguments

localelocale
使用するロケール。The locale to use

戻り値Return Value

これらの関数は、正常に変換および代入されたフィールドの数を返します。読み込まれただけで代入されなかったフィールドは戻り値には含まれません。Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. 戻り値が 0 の場合は、代入されたフィールドがなかったことを示します。A return value of 0 indicates that no fields were assigned. エラーの場合、または最初の変換の前に文字列の末尾に到達した場合、戻り値はEOFになります。The return value is EOF for an error or if the end of the string is reached before the first conversion.

BufferまたはformatNULLポインターの場合は、「パラメーターの検証」で説明されているように、無効なパラメーターハンドラーが呼び出されます。If buffer or format is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 実行の継続が許可された場合、これらの関数は-1 を返し、 errnoEINVALに設定します。If execution is allowed to continue, these functions return -1 and set errno to EINVAL

エラー コードの詳細については、「errno、_doserrno、_sys_errlist、_sys_nerr」をご覧ください。For information about these and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

RemarksRemarks

Sscanf_s関数は、各引数によって指定された場所にバッファーからデータを読み取ります。The sscanf_s function reads data from buffer into the location that's given by each argument. 書式指定文字列の後の引数は、形式の型指定子に対応する型を持つ変数へのポインターを指定します。The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in format. 安全性の低いバージョンsscanfとは異なり、 [] で囲まれている型フィールド文字ccss、または文字列コントロールセットを使用する場合は、バッファーサイズのパラメーターが必要です。Unlike the less secure version sscanf, a buffer size parameter is required when you use the type field characters c, C, s, S, or string control sets that are enclosed in []. バッファー サイズ (文字単位) は、バッファー サイズが必要な各バッファーの後に追加パラメーターとして指定する必要があります。The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. たとえば、文字列を読み込む場合、その文字列のバッファー サイズは次のように渡されます。For example, if you are reading into a string, the buffer size for that string is passed as follows:

wchar_t ws[10];
swscanf_s(in_str, L"%9s", ws, (unsigned)_countof(ws)); // buffer size is 10, width specification is 9

バッファー サイズには、終端 null も含まれます。The buffer size includes the terminating null. 読み取られたトークンがバッファーに確実に収まるように、幅指定フィールドが使用される場合もあります。A width specification field may be used to ensure that the token that's read in will fit into the buffer. 幅指定フィールドが使用されない場合で、読み取られたトークンがバッファーに収まらない場合、そのバッファーには何も書き込まれません。If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer.

文字の場合、次のように 1 文字読み込む場合もあります。In the case of characters, a single character may be read as follows:

wchar_t wc;
swscanf_s(in_str, L"%c", &wc, 1);

次に、この例では、入力文字列とデータ ストアから 1 つの文字をワイド文字バッファーに読み込みます。This example reads a single character from the input string and then stores it in a wide-character buffer. null で終わらない文字列に対して複数の文字列を読み込む場合、幅指定とバッファー サイズとして符号なし整数が使用されます。When you read multiple characters for non-null terminated strings, unsigned integers are used as the width specification and the buffer size.

char c[4];
sscanf_s(input, "%4c", &c, (unsigned)_countof(c)); // not null terminated

詳細については、「scanf_s、_scanf_s_l、wscanf_s、_wscanf_s_l」と「scanf 関数の型フィールド文字」を参照してください。For more information, see scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l and scanf Type Field Characters.

注意

Size パラメーターは、 size_tではなくunsigned型です。The size parameter is of type unsigned, not size_t. 64ビットターゲットのコンパイル時には、静的なキャストを使用して、またはsizeof 結果を正しいサイズに変換します。When compiling for 64-bit targets, use a static cast to convert _countof or sizeof results to the correct size.

Format引数は、入力フィールドの解釈を制御し、 scanf_s関数のformat引数と同じ形式と機能を持ちます。The format argument controls the interpretation of the input fields and has the same form and function as the format argument for the scanf_s function. 重なり合う文字列間でコピーした場合の動作は未定義です。If copying occurs between strings that overlap, the behavior is undefined.

swscanf_sは、 sscanf_sのワイド文字バージョンです。swscanf_sの引数はワイド文字列です。swscanf_s is a wide-character version of sscanf_s; the arguments to swscanf_s are wide-character strings. sscanf_sでは、マルチバイトの16進文字は処理されません。sscanf_s does not handle multibyte hexadecimal characters. swscanf_sでは、Unicode の全角16進数または "互換ゾーン" の文字は処理されません。swscanf_s does not handle Unicode full-width hexadecimal or "compatibility zone" characters. それ以外の場合、 swscanf_ssscanf_sは同じように動作します。Otherwise, swscanf_s and sscanf_s behave identically.

_Lサフィックスが付いているこれらの関数のバージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメーターを使用する点を除いて同じです。The versions of these functions that have the _l suffix are identical except that they use the locale parameter that's passed in instead of the current thread locale.

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
stscanf_s (_d)_stscanf_s sscanf_ssscanf_s sscanf_ssscanf_s swscanf_sswscanf_s
_stscanf_s_l_stscanf_s_l _sscanf_s_l_sscanf_s_l _sscanf_s_l_sscanf_s_l _swscanf_s_l_swscanf_s_l

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
sscanf_s_sscanf_s_lsscanf_s, _sscanf_s_l <stdio.h><stdio.h>
swscanf_s_swscanf_s_lswscanf_s, _swscanf_s_l <stdio.h> または <wchar.h><stdio.h> or <wchar.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus null terminator
   sscanf_s( tokenstring, "%s", s, (unsigned)_countof(s) );
   sscanf_s( tokenstring, "%c", &c, (unsigned)sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}
String    = 15
Character = 1
Integer:  = 15
Real:     = 15.000000

関連項目See also

ストリーム入出力Stream I/O
fscanf、_fscanf_l、fwscanf、_fwscanf_lfscanf, _fscanf_l, fwscanf, _fwscanf_l
scanf、_scanf_l、wscanf、_wscanf_lscanf, _scanf_l, wscanf, _wscanf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
snprintf、_snprintf、_snprintf_l、_snwprintf、_snwprintf_lsnprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l