sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l

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

文字列に書式付きデータを書き込みます。これらの関数のセキュリティを強化したバージョンについては、「sprintf_s、_sprintf_s_l、swprintf_s、_swprintf_s_l」を参照してください。セキュリティを強化したバージョンの swprintf と _swprintf_l は、count パラメーターを受け取りません。

int sprintf(
   char *buffer,
   const char *format [,
   argument] ... 
);
int _sprintf_l(
   char *buffer,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int swprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument]...
);
int _swprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
);
int __swprintf_l(
   wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
);
template <size_t size>
int sprintf(
   char (&buffer)[size],
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _sprintf_l(
   char (&buffer)[size],
   const char *format,
   locale_t locale [,
   argument] ... 
); // C++ only
template <size_t size>
int swprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument]...
); // C++ only
template <size_t size>
int _swprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
); // C++ only

パラメーター

buffer
出力の格納場所。
count
この関数の Unicode バージョンで格納する最大文字数。
format
書式指定文字列。
argument
省略可能な引数。
locale
使用するロケール。

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

戻り値

書き込まれた文字数を返します。エラーが発生した場合は -1 を返します。 buffer または format が null ポインターの場合は、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、これらの関数は -1 を返し、errno を EINVAL に設定します。

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

解説

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

セキュリティに関するメモ
sprintf 関数を使用する際、書き込まれる文字数は制限できないため、sprintf 関数を使用しているコードでは、バッファーオーバーランが発生しやすくなります。関連する関数である _snprintf の使用を検討してください。この関数では、buffer に書き込まれる最大文字数を指定できます。_scprintf を使用すると、必要なバッファーのサイズを調べることができます。また、format にユーザー定義の文字列を指定しないでください。

sprintf 関数を使用する際、書き込まれる文字数は制限できないため、sprintf 関数を使用しているコードでは、バッファーオーバーランが発生しやすくなります。関連する関数である _snprintf の使用を検討してください。この関数では、buffer に書き込まれる最大文字数を指定できます。_scprintf を使用すると、必要なバッファーのサイズを調べることができます。また、format にユーザー定義の文字列を指定しないでください。

swprintf は sprintf のワイド文字バージョンであり、swprintf のポインター引数はワイド文字列です。 swprintf と sprintf では、エンコーディングエラーの検出動作が異なる場合があります。 swprintf と fwprintf の動作は同じですが、swprintf は FILE 型の出力先ではなく文字列に出力を書き込む点と、swprintf には書き込む最大文字数を指定する count パラメーターが必要である点が異なります。 _l サフィックスが付いているこれらの関数の各バージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメーターを使用する点を除いて同じです。

swprintfISO C 2 番目のパラメーターを必要とする標準に準拠しているcount、タイプのsize_t。古い非標準の動作を強制的に実行させるには、_CRT_NON_CONFORMING_SWPRINTFS を定義します。この古い動作は、将来的には削除される可能性があるので、規格に準拠した新しい動作を使用するようにコードを変更する必要があります。

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

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

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_stprintf	sprintf	sprintf	swprintf
_stprintf_l	_sprintf_l	_sprintf_l	__swprintf_l

必要条件

ルーチン	必須ヘッダー
sprintf, _sprintf_l	<stdio.h>
swprintf, _swprintf_l	<stdio.h> または <wchar.h>

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

使用例

// crt_sprintf.c
// compile with: /W3
// This program uses sprintf 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( buffer,     "   String:    %s\n", s ); // C4996
   j += sprintf( buffer + j, "   Character: %c\n", c ); // C4996
   j += sprintf( buffer + j, "   Integer:   %d\n", i ); // C4996
   j += sprintf( buffer + j, "   Real:      %f\n", fp );// C4996
   // Note: sprintf is deprecated; consider using sprintf_s instead

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

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

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