sprintf_s、_sprintf_s_l、swprintf_s、_swprintf_s_lsprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

文字列に書式付きデータを書き込みます。Write formatted data to a string. これらは、「CRT のセキュリティ機能」の説明にあるとおり、セキュリティが強化されたバージョンの sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l です。These are versions of sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l with security enhancements as described in Security Features in the CRT.

構文Syntax

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

パラメーターParameters

バッファーbuffer
出力の格納場所。Storage location for output

sizeOfBuffersizeOfBuffer
格納する最大文字数。Maximum number of characters to store.

formatformat
書式指定文字列。Format-control string

......
書式設定する省略可能な引数Optional arguments to be formatted

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

詳細については、「 printf 関数と wprintf 関数の書式指定フィールド」を参照してください。For more information, see Format Specifications.

戻り値Return Value

書き込まれた文字数。エラーが発生した場合は-1。The number of characters written, or -1 if an error occurred. Bufferまたはformatが null ポインターの場合、 sprintf_sswprintf_sは-1 を返し、 errnoEINVALに設定します。If buffer or format is a null pointer, sprintf_s and swprintf_s return -1 and set errno to EINVAL.

sprintf_sは、バッファーに格納されているバイト数を返します。終端の null 文字はカウントされません。sprintf_s returns the number of bytes stored in buffer, not counting the terminating null character. swprintf_sは、バッファーに格納されているワイド文字の数を返します。終端の null ワイド文字はカウントされません。swprintf_s returns the number of wide characters stored in buffer, not counting the terminating null wide character.

RemarksRemarks

Sprintf_s関数は、一連の文字と値の書式を設定し、バッファーに格納します。The sprintf_s function formats and stores a series of characters and values in buffer. 引数(存在する場合) は、対応する書式指定に従って変換および出力されます。Each argument (if any) is converted and output according to the corresponding format specification in format. 形式は通常の文字で構成され、 printfformat引数と同じ形式と機能を持ちます。The format consists of ordinary characters and has the same form and function as the format argument for printf. 最後に書き込まれる文字の後に NULL 文字が追加されます。A null character is appended after the last character written. 重なり合う文字列間でコピーした場合の動作は未定義です。If copying occurs between strings that overlap, the behavior is undefined.

Sprintf_ssprintfの主な違いは、 sprintf_sでは書式指定文字列が有効な書式指定文字であることを確認するのに対し、 sprintfでは書式指定文字列またはバッファーがNULLポインターであるかどうかのみをチェックするためです。One main difference between sprintf_s and sprintf is that sprintf_s checks the format string for valid formatting characters, whereas sprintf only checks if the format string or buffer are NULL pointers. いずれかのチェックが失敗した場合、「 Parameter Validation」に説明されているように、無効なパラメーター ハンドラーが呼び出されます。If either check fails, the invalid parameter handler is invoked, as described in Parameter Validation. 実行の継続が許可された場合、この関数は-1 を返し、 errnoEINVALに設定します。If execution is allowed to continue, the function returns -1 and sets errno to EINVAL.

Sprintf_ssprintfのもう1つの主な違いは、 sprintf_sでは、出力バッファーのサイズを文字数で指定する長さのパラメーターを受け取ることです。The other main difference between sprintf_s and sprintf is that sprintf_s takes a length parameter specifying the size of the output buffer in characters. バッファーが、終端の null を含め、書式設定されたテキストに対して小さすぎる場合は、バッファー [0] に null 文字を配置することでバッファーが空の文字列に設定され、無効なパラメーターハンドラーが呼び出されます。If the buffer is too small for the formatted text, including the terminating null, then the buffer is set to an empty string by placing a null character at buffer[0], and the invalid parameter handler is invoked. _Snprintfとは異なり、 sprintf_sでは、バッファーサイズがゼロでない限り、バッファーは null で終わることが保証されます。Unlike _snprintf, sprintf_s guarantees that the buffer will be null-terminated unless the buffer size is zero.

swprintf_sは、 sprintf_sのワイド文字バージョンです。swprintf_sへのポインター引数はワイド文字列です。swprintf_s is a wide-character version of sprintf_s; the pointer arguments to swprintf_s are wide-character strings. Swprintf_sでのエンコードエラーの検出は、 sprintf_sの場合とは異なる場合があります。Detection of encoding errors in swprintf_s may differ from that in sprintf_s. _Lサフィックスを持つこれらの関数のバージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメーターを使用する点を除いて同じです。The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically, which eliminates the need to specify a size argument, and they can automatically replace older, non-secure functions with their newer, secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

バッファーが小さすぎる場合に何が起こるかについて、追加の制御を提供するsprintf_sのバージョンがあります。There are versions of sprintf_s that offer additional control over what happens if the buffer is too small. 詳細については、「 _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l」を参照してください。For more information, see _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

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

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
stprintf_s (_d)_stprintf_s sprintf_ssprintf_s sprintf_ssprintf_s swprintf_sswprintf_s
_stprintf_s_l_stprintf_s_l _sprintf_s_l_sprintf_s_l _sprintf_s_l_sprintf_s_l _swprintf_s_l_swprintf_s_l

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
sprintf_s_sprintf_s_lsprintf_s, _sprintf_s_l C: <stdio.h>C: <stdio.h>

C++: <cstdio> または <stdio.h>C++: <cstdio> or <stdio.h>
swprintf_s_swprintf_s_lswprintf_s, _swprintf_s_l C: <stdio.h> または <wchar.h>C: <stdio.h> or <wchar.h>

C++: <cstdio>、<cwchar>、<stdio.h> または <wchar.h>C++: <cstdio>, <cwchar>, <stdio.h> or <wchar.h>

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

Example

// 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

Example

// 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

関連項目See also

ストリーム入出力Stream I/O
fprintf、_fprintf_l、fwprintf、_fwprintf_lfprintf, _fprintf_l, fwprintf, _fwprintf_l
printf、_printf_l、wprintf、_wprintf_lprintf, _printf_l, wprintf, _wprintf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
scanf、_scanf_l、wscanf、_wscanf_lscanf, _scanf_l, wscanf, _wscanf_l
sscanf、_sscanf_l、swscanf、_swscanf_lsscanf, _sscanf_l, swscanf, _swscanf_l
vprintf 系関数vprintf Functions