_snprintf、_snprintf_l、_snwprintf、_snwprintf_l

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

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

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
格納する最大文字数。
format
書式指定文字列。
argument
省略可能な引数。
locale
使用するロケール。

戻り値

len を書式付きデータ文字列 (終端の null は含まない) の長さとします。_snprintf 関数の場合、len と count はバイト単位、_snwprintf 関数の場合はワイド文字単位になります。

len < count の場合、len の文字数が buffer に格納されて、終端の null が追加され、len が返されます。

len = count の場合、len の文字数が buffer に格納されて、終端の null は追加されず、len が返されます。

len > count の場合、count の文字数が buffer に格納されて、終端の null は追加されず、負の値が返されます。

buffer が null ポインタで count が 0 以外の場合、または format が null ポインタの場合は、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、これらの関数は -1 を返し、errno を EINVAL に設定します。

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

解説

_snprintf 関数は、count 以下の文字数を書式指定して、buffer に格納し、書式付き文字列の長さが確実に count 文字数未満の場合には終端の null 文字を追加します。各 argument (指定されている場合) は、format 中の対応する書式指定に応じて変換され、格納されます。format は通常の文字で構成し、その形式と機能は printf 関数の format と同じです。重なり合う文字列間でコピーした場合の動作は未定義です。

セキュリティに関するメモ :
format にユーザー定義の文字列を指定しないでください。この関数では NULL で終わることが保証されないため (特に戻り値が count の場合)、この関数の後に、終端の null を追加するコードを続けるようにしてください。詳細については、「Avoiding Buffer Overruns」を参照してください。

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

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

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

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

Tchar.h のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

必要条件

ルーチン	必須ヘッダー
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> または <wchar.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// 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 nul! */
   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 nul because _snprintf doesn't necessarily (if the string 
       * fits without the terminal nul, 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