`snprintf`、 `_snprintf`、 `_snprintf_l`、 `_snwprintf`、 `_snwprintf_l`

[アーティクル]
08/03/2024

文字列に書式付きデータを書き込みます。これらの関数のセキュリティを強化したバージョンを使用できます。「_snprintf_s、_snprintf_s_l、_snwprintf_s、_snwprintf_s_l」を参照してください。

構文

int snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
);

int _snwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument] ...
);

int _snwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

template <size_t size>
int _snprintf(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
); // C++ only

パラメーター

buffer
出力の格納場所。

count
書き込む最大文字数。 wchar_tを受け取る関数の場合、書き込むワイド文字の最大数です。

format
書式指定文字列。

argument
省略可能な引数。

locale
出力の書式設定に使用するロケール。

詳細については、「 Format の仕様構文: printf 関数と wprintf 関数を参照してください。

戻り値

countが無視された場合にバッファーに書き込まれた文字数。カウントには、終端の NULL 文字は含まれません。

終了lenNULLを含めず、書式設定されたデータ文字列の長さを指定します。
すべての関数で、 len < countした場合、 len 文字が bufferに格納され、null ターミネータが追加され、終了 NULLを含まない書き込まれた文字数が返されます。

これらの関数のワイド文字バージョンは、終端の NULLを含まない、書き込まれたワイド文字の数を返します。

詳細については、 Behavior の概要を参照してください。

解説

Visual Studio 2015 および Windows 10 で UCRT と共に開始する場合、 snprintf は _snprintfと同一ではなくなります。 snprintf動作が C99 標準準拠になりました。違いは、バッファーが不足した場合、 snprintf はバッファーの末尾を null で終了し、必要な文字数を返しますが、 _snprintf はバッファーを null 終了せず、-1 を返します。また、 snprintf() はバッファーを null で終了しないため、出力にもう 1 つの文字が含まれます。

snprintfおよび関数の_snprintf ファミリは、bufferにcount以下の文字を書式設定して格納します。
snprintf は常に終端 NULL 文字を格納し、必要に応じて出力を切り捨てます。
snprintfが >count - 1 の値を返す場合、出力は切り捨てられました。
_snprintf関数ファミリは、書式設定された文字列の長さが厳密にcount文字より小さい場合にのみ、終了NULL文字を追加します。
各 argument (指定されている場合) は、 format中の対応する書式指定に応じて変換され、格納されます。書式は通常の文字で構成され、その形式と機能は printf の format 引数と同じです。重なり合う文字列間でコピーした場合の動作は未定義です。

動作の概要

次の表の場合:

sizeOfBufferbufferのサイズにします。関数が char バッファーを受け取る場合、サイズはバイト単位です。関数が wchar_t バッファーを受け取る場合、サイズは 16 ビットワードの数を指定します。
書式設定されたデータのサイズ len します。関数が char バッファーを受け取る場合、サイズはバイト単位です。関数が wchar_t バッファーを受け取る場合、サイズは 16 ビットワードの数を指定します。
文字とは、char バッファーを受け取る関数のchar文字と、wchar_t バッファーを受け取る関数のwchar_t文字を指します。
無効なパラメーターハンドラーの詳細については、「パラメーターの検証を参照してください。

条件	Behavior	戻り値	`errno`	無効なパラメーターハンドラーを呼び出す
成功	指定した書式指定文字列を使用して、バッファーに文字を書き込みます。	書き込まれる文字数です。	該当なし	いいえ
書式設定中のエンコードエラー	文字列指定子 `s`、 `S`、または `Z`の書式指定処理を停止すると、バッファーの先頭に `NULL` が配置されます。	-1	`EILSEQ` (42)	いいえ
書式設定中のエンコードエラー	文字指定子の処理 `c` または `C`場合、無効な文字はスキップされます。書き込まれた文字数は、スキップされた文字に対してインクリメントされず、データも書き込まれません。書式指定の処理は、エンコードエラーで指定子をスキップした後も続行されます。	終了 `NULL`を含まない、書き込まれた文字数。	`EILSEQ` (42)	いいえ
`buffer == NULL` および `count != 0`	無効なパラメーターハンドラーの実行後も実行が続行される場合は、 `errno` を設定し、負の値を返します。	-1	`EINVAL` (22)	はい
`count == 0`	終了 `NULL`を含まない、書き込まれた文字数。この結果を使用して、文字列と終了 `NULL`に十分なバッファー領域を割り当て、関数を再度呼び出してバッファーを埋めることができます。	該当なし	いいえ
`count < 0`	Unsafe: 値は符号なしとして扱われ、バッファーに続くメモリが上書きされる大きな値が作成される可能性があります。	書き込まれた文字数	該当なし	いいえ
`count < sizeOfBuffer` および `len <= count`	すべてのデータが書き込まれ、終了 `NULL` が追加されます。	終了 `NULL`を含まない、書き込まれた文字数。	該当なし	いいえ
`count < sizeOfBuffer` および `len > count`	最初の `count-1` 文字の後に null 終端記号が書き込まれます。	書き込まれた文字の数が、null ターミネータを含まない、出力する文字数と一致 `count` 。	該当なし	いいえ
`count >= sizeOfBuffer` および `len < sizeOfBuffer`	すべてのデータは、終了 `NULL`で書き込まれます。	終了 `NULL`を含まない、書き込まれた文字数。	該当なし	いいえ
`count >= sizeOfBuffer` および `len >= sizeOfBuffer`	Unsafe: バッファーの後のメモリを上書きします。	終了 `NULL`を含まない、書き込まれた文字数。	該当なし	いいえ
`format == NULL`	データは書き込みされません。無効なパラメーターハンドラーの実行後も実行が続行される場合は、 `errno` を設定し、負の値を返します。	-1	`EINVAL` (22)	はい

これらのエラーコードおよびその他のエラーコードの詳細については、「_doserrno、errno、_sys_errlist、_sys_nerr」を参照してください。

重要

format にユーザー定義の文字列を指定しないでください。 _snprintf 関数では null で終わることが保証されないため (特に戻り値が count の場合)、これらの関数の後に、終端の null を追加するコードが続いていることを確認してください。詳細については、「バッファーオーバーランの回避」を参照してください。

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 にリンクします。

_snwprintf は _snprintfのワイド文字バージョンであり、 _snwprintf のポインター引数はワイド文字列です。 _snwprintfでのエンコードエラーの検出は、_snprintfでの検出とは異なる場合があります。 _snwprintfと同様に、 swprintfでは出力が FILE型の出力先ではなく文字列に書き込まれます。

これらの関数のうち _l サフィックスが付けられたバージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメーターを使用する点を除いて同じです。

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

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

`Tchar.h` ルーチン	`_UNICODE` と `_MBCS` が定義されていない	`_MBCS` が定義されている	`_UNICODE` が定義されている
`_sntprintf`	`_snprintf`	`_snprintf`	`_snwprintf`
`_sntprintf_l`	`_snprintf_l`	`_snprintf_l`	`_snwprintf_l`

要件

ルーチンによって返される値	必須ヘッダー
`snprintf`、 `_snprintf`、 `_snprintf_l`	`<stdio.h>`
`_snwprintf`, `_snwprintf_l`	`<stdio.h>` または `<wchar.h>`

互換性の詳細については、「 Compatibility」を参照してください。

例

// crt_snprintf.c
// compile with: /W3
#include <stdio.h>
#include <stdlib.h>

#if !defined(__cplusplus)
typedef int bool;
const bool true = 1;
const bool false = 0;
#endif

#define FAIL 0 // change to 1 and see what happens

int main(void)
{
   char buffer[200];
   const static char s[] = "computer"
#if FAIL
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
#endif
   ;
   const char c = 'l';
   const int i = 35;
#if FAIL
   const double fp = 1e300; // doesn't fit in the buffer
#else
   const double fp = 1.7320534;
#endif
   /* !subtract one to prevent "squeezing out" the terminal null! */
   const int bufferSize = sizeof(buffer)/sizeof(buffer[0]) - 1;
   int bufferUsed = 0;
   int bufferLeft = bufferSize - bufferUsed;
   bool bSuccess = true;
   buffer[0] = 0;

   /* Format and print various data: */

   if (bufferLeft > 0)
   {
      int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
      bufferLeft, "   String: %s\n", s ); // C4996
      // Note: _snprintf is deprecated; consider _snprintf_s instead
      if (bSuccess = (perElementBufferUsed >= 0))
      {
         bufferUsed += perElementBufferUsed;
         bufferLeft -= perElementBufferUsed;
         if (bufferLeft > 0)
         {
            int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
            bufferLeft, "   Character: %c\n", c ); // C4996
            if (bSuccess = (perElementBufferUsed >= 0))
            {
               bufferUsed += perElementBufferUsed;
               bufferLeft -= perElementBufferUsed;
               if (bufferLeft > 0)
               {
                  int perElementBufferUsed = _snprintf(&buffer
                  [bufferUsed], bufferLeft, "   Integer: %d\n", i ); // C4996
                  if (bSuccess = (perElementBufferUsed >= 0))
                  {
                     bufferUsed += perElementBufferUsed;
                     bufferLeft -= perElementBufferUsed;
                     if (bufferLeft > 0)
                     {
                        int perElementBufferUsed = _snprintf(&buffer
                        [bufferUsed], bufferLeft, "   Real: %f\n", fp ); // C4996
                        if (bSuccess = (perElementBufferUsed >= 0))
                        {
                           bufferUsed += perElementBufferUsed;
                        }
                     }
                  }
               }
            }
         }
      }
   }

   if (!bSuccess)
   {
      printf("%s\n", "failure");
   }
   else
   {
      /* !store null because _snprintf doesn't necessarily (if the string
       * fits without the terminal null, but not with it)!
       * bufferUsed might be as large as bufferSize, which normally is
       * like going one element beyond a buffer, but in this case
       * subtracted one from bufferSize, so we're ok.
       */
      buffer[bufferUsed] = 0;
      printf( "Output:\n%s\ncharacter count = %d\n", buffer, bufferUsed );
   }
   return EXIT_SUCCESS;
}

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

character count = 69

次の方法で共有

`snprintf`、 `_snprintf`、 `_snprintf_l`、 `_snwprintf`、 `_snwprintf_l`

構文

パラメーター

戻り値

解説

動作の概要

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

要件

例

関連項目

フィードバック

その他のリソース

次の方法で共有

snprintf、 _snprintf、 _snprintf_l、 _snwprintf、 _snwprintf_l

構文

パラメーター

戻り値

解説

動作の概要

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

要件

例

関連項目

フィードバック

その他のリソース

`snprintf`、 `_snprintf`、 `_snprintf_l`、 `_snwprintf`、 `_snwprintf_l`

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