sprintf_s、_sprintf_s_l、swprintf_s、_swprintf_s_l

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

文字列に書式付きデータを書き込みます。これらの関数は、「CRT のセキュリティ機能」に説明されているように、sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l のセキュリティが強化されたバージョンです。

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format [,
   argument] ... 
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format [,
   argument]...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   locale_t locale [,
   argument]…
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format [,
   argument]...
); // C++ only

パラメーター

buffer
出力の格納場所。
sizeOfBuffer
格納する最大文字数。
format
書式指定文字列。
argument
省略可能な引数。
locale
使用するロケール。

詳細については、「scanf 関数と wscanf 関数の書式指定フィールド」を参照してください。

戻り値

書き込まれた文字数を返します。エラーが発生した場合は -1 を返します。 buffer または format が null ポインターである場合、sprintf_s および swprintf_s は -1 を返し、errno を EINVAL に設定します。

sprintf_s 関数は、buffer に格納されているバイト数を返します。終端の null 文字は含まれません。 swprintf_s 関数は、buffer に格納されているワイド文字数を返します。終端の null 文字は含まれません。

解説

sprintf_s 関数は、一連の文字と値の書式を指定して、buffer に格納します。各 argument (指定されている場合) は、format 中の対応する書式指定に応じて変換され、格納されます。 format は通常の文字で構成し、その形式と機能は printf 関数の format と同じです。最後に書き込まれる文字の後に NULL 文字が追加されます。重なり合う文字列間でコピーした場合の動作は未定義です。

sprintf_s と sprintf 間の主な違いとしては、sprintf_s は書式指定文字列の有効な書式指定文字をチェックしますが、sprintf は書式指定文字列またはバッファーが NULL ポインターかどうかのみをチェックします。いずれかのチェックが失敗した場合、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、関数は -1 を返し、errno を EINVAL に設定します。

sprintf_s と sprintf 間のもう 1 つの違いとして、sprintf_s は、出力バッファーのサイズを文字数で指定する長さパラメーターを受け取ります。バッファーが小さすぎて出力テキストを格納できない場合、バッファーは、空の文字列に設定され、無効なパラメーターハンドラーが呼び出されます。 snprintf とは異なり、sprintf_s では、必ずバッファーは null で終わります (バッファーサイズがゼロでない限り)。

swprintf_s は sprintf_s のワイド文字バージョンであり、swprintf_s のポインター引数はワイド文字列です。 swprintf_s と sprintf_s では、エンコーディングエラーの検出動作が異なる場合があります。これらの関数のうち _l サフィックスが付けられたバージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメーターを使用する点を除いて同じです。

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

sprintf_s には、バッファーが小さすぎる場合に発生する状況を制御できるバージョンもあります。詳細については、「_snprintf_s、_snprintf_s_l、_snwprintf_s、_snwprintf_s_l」を参照してください。

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

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

必要条件

ルーチン	必須ヘッダー
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> または <wchar.h>

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

使用例

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data: 
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}