snprintf、 _snprintf、 _snprintf_l、 _snwprintf、 _snwprintf_l

文字列に書式付きデータを書き込みます。 これらの関数のセキュリティを強化したバージョンを使用できます。「_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文字を指します。
• 無効なパラメーター ハンドラーの詳細については、「 パラメーターの検証を参照してください。

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

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

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

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

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

要件

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

関連項目

ストリーム入出力
sprintf、 _sprintf_l、 swprintf、 _swprintf_l、 __swprintf_l
fprintf、 _fprintf_l、 fwprintf、 _fwprintf_l
printf、 _printf_l、 wprintf、 _wprintf_l
scanf、 _scanf_l、 wscanf、 _wscanf_l
sscanf、 _sscanf_l、 swscanf、 _swscanf_l
vprintf 関数