sprintf_s
、 _sprintf_s_l
、 swprintf_s
、 _swprintf_s_l
文字列に書式付きデータを書き込みます。 これらの関数は、「CRT のセキュリティ機能で説明されているように、セキュリティが強化されたsprintf
、_sprintf_l
、swprintf
、_swprintf_l
、__swprintf_l
のバージョンです。
構文
int sprintf_s(
char *buffer,
size_t sizeOfBuffer,
const char *format,
...
);
int _sprintf_s_l(
char *buffer,
size_t sizeOfBuffer,
const char *format,
_locale_t locale,
...
);
int swprintf_s(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
...
);
int _swprintf_s_l(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
_locale_t locale,
...
);
template <size_t size>
int sprintf_s(
char (&buffer)[size],
const char *format,
...
); // C++ only
template <size_t size>
int swprintf_s(
wchar_t (&buffer)[size],
const wchar_t *format,
...
); // C++ only
パラメーター
buffer
出力の格納場所。
sizeOfBuffer
格納する最大文字数。
format
書式指定文字列。
...
書式設定する省略可能な引数
locale
使用するロケール。
詳細については、「書式指定構文」を参照してください。
戻り値
書き込まれた文字数を返します。エラーが発生した場合は -1 を返します。 buffer
または format
が null ポインターである場合、sprintf_s
および swprintf_s
は -1 を返し、errno
を EINVAL
に設定します。
sprintf_s
関数は、 buffer
に格納されているバイト数を返します。終端の null 文字は含まれません。 swprintf_s
は、buffer
に格納されているワイド文字数を返します。終端の null ワイド文字は含まれません。
解説
sprintf_s
関数は、一連の文字と値の書式を指定して、 buffer
に格納します。 各 argument
(指定されている場合) は、 format
中の対応する書式指定に応じて変換され、格納されます。 書式は通常の文字で構成され、その形式と機能は printf
の format
引数と同じです。 最後に書き込まれる文字の後に NULL 文字が追加されます。 重なり合う文字列間でコピーした場合の動作は未定義です。
sprintf_s
と sprintf
間の主な違いとしては、 sprintf_s
は書式指定文字列の有効な書式指定文字をチェックしますが、 sprintf
は書式指定文字列またはバッファーが NULL
ポインターかどうかのみをチェックします。 いずれかのチェックが失敗した場合は、「パラメーターの検証 で説明されているように、無効なパラメーター ハンドラーが呼び出。 実行の継続が許可された場合、この関数は -1 を返し、 errno
を EINVAL
に設定します。
sprintf_s
と sprintf
間のもう 1 つの違いとして、 sprintf_s
は、出力バッファーのサイズを文字数で指定する長さパラメーターを受け取ります。 バッファーが、終端の null を含めた書式付きテキストに対して小さすぎる場合は、バッファーは buffer[0]
で null 文字を配置することで空の文字列に設定され、無効なパラメーター ハンドラーが呼び出されます。 _snprintf
とは異なり、 sprintf_s
では、バッファー サイズがゼロでない限り、必ずバッファーは null で終わります。
swprintf_s
は sprintf_s
のワイド文字バージョンであり、 swprintf_s
のポインター引数はワイド文字列です。 swprintf_s
でのエンコード エラーの検出は、sprintf_s
での検出とは異なる場合があります。 これらの関数のうち _l
サフィックスが付けられたバージョンは、現在のスレッド ロケールの代わりに渡されたロケール パラメーターを使用する点を除いて同じです。
C++ では、これらの関数の使用がテンプレートのオーバーロードによって簡略化されます。 オーバーロードではバッファーの長さを自動的に推論できるため、size 引数を指定する必要がなくなります。 また、古いセキュリティで保護されていない関数を、より新しい、より安全な関数に自動的に置き換えることができます。 詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。
バッファーが小さすぎる場合の動作をより細かく制御できるバージョンの sprintf_s
があります。 詳細については、「_snprintf_s
、_snprintf_s_l
、_snwprintf_s
、_snwprintf_s_l
」を参照してください。
重要
Windows 10 バージョン 2004 (ビルド 19041) 以降の printf
ファミリの関数では、丸め処理の IEEE 754 の規則に従って、正確に表現可能な浮動小数点数が出力されます。 以前のバージョンの Windows では、"5" で終わる正確に表現可能な浮動小数点数は常に切り上げられていました。 IEEE 754 では、最も近い偶数に丸める ("銀行型丸め" とも呼ばれます) 必要があることが示されています。 たとえば、printf("%1.0f", 1.5)
と printf("%1.0f", 2.5)
の両方を 2 に丸める必要があります。 以前は、1.5 は 2 に、2.5 は 3 に丸められていました。 この変更は、正確に表現可能な数値にのみ影響します。 たとえば、2.35 (メモリで表される場合は 2.35000000000000008 に近い) は、2.4 に切り上げられます。 これらの関数によって実行される丸め処理では、fesetround
によって設定された浮動小数点丸めモードにも従うようになりました。 以前は、丸め処理には常に FE_TONEAREST
の動作が選択されていました。 この変更は、Visual Studio 2019 バージョン 16.2 以降を使用してビルドされたプログラムにのみ影響します。 従来の浮動小数点丸め動作を使用するには、'legacy_stdio_float_rounding.obj' にリンクします。
汎用テキスト ルーチンのマップ
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 |
C: <stdio.h> C++: <cstdio> または <stdio.h> |
swprintf_s , _swprintf_s_l |
C: <stdio.h> または <wchar.h> C++: <cstdio>、<cwchar>、<stdio.h>、または <wchar.h> |
互換性の詳細については、「 Compatibility」を参照してください。
例: sprintf_s を使ってデータの書式を設定する
// 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
関連項目
ストリーム入出力
fprintf
、 _fprintf_l
、 fwprintf
、 _fwprintf_l
printf
、 _printf_l
、 wprintf
、 _wprintf_l
sprintf
、 _sprintf_l
、 swprintf
、 _swprintf_l
、 __swprintf_l
scanf
、 _scanf_l
、 wscanf
、 _wscanf_l
sscanf
、 _sscanf_l
、 swscanf
、 _swscanf_l
vprintf
関数