書き込まれた文字数を返します。エラーが発生した場合は -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」を参照してください。

互換性の詳細については、「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 );
}

出力

Output:
   String:    computer
   Character: l
   Integer:   35
   Real:      1.732053

character count = 79

// 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 );
}

出力

wrote 11 characters
wrote -1 characters

System::String::Format

関連項目