snprintf、_snprintf、_snprintf_l、_snwprintf、_snwprintf_lsnprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l

文字列に書式付きデータを書き込みます。Writes formatted data to a string. これらの関数のセキュリティを強化したバージョンを使用できます。「_snprintf_s、_snprintf_s_l、_snwprintf_s、_snwprintf_s_l」をご覧ください。More secure versions of these functions are available; see _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

構文Syntax

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

パラメーターParameters

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

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

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

argumentargument
省略可能な引数。Optional arguments.

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

詳細については、「書式指定構文: printf 関数と wprintf 関数」をご覧ください。For more information, see Format Specification Syntax: printf and wprintf Functions.

戻り値Return Value

Lenには、書式設定されたデータ文字列の長さを指定します。終端の null は含まれません。Let len be the length of the formatted data string, not including the terminating null. Lencountはどちらも、 snprintf_snprintfの場合はバイト、 _snwprintfの場合はワイド文字です。Both len and count are in bytes for snprintf and _snprintf, wide characters for _snwprintf.

すべての関数について、 len < countの場合はlen文字がバッファーに格納され、null 終端記号が追加され、 lenが返されます。For all functions, if len < count, len characters are stored in buffer, a null-terminator is appended, and len is returned.

Snprintf関数は、 lencount以上の場合に、null 終端記号をにbuffer[count-1]配置することによって、出力を切り捨てます。The snprintf function truncates the output when len is greater than or equal to count, by placing a null-terminator at buffer[count-1]. 返される値はlenで、 countが十分に大きい場合に出力された文字数です。The value returned is len, the number of characters that would have been output if count was large enough. Snprintf関数は、エンコードエラーが発生した場合に負の値を返します。The snprintf function returns a negative value if an encoding error occurs.

Snprintf以外のすべての関数について、 len = countの場合は len 文字がバッファーに格納され、null終端文字は追加されず、 lenが返されます。For all functions other than snprintf, if len = count, len characters are stored in buffer, no null-terminator is appended, and len is returned. Len > countcount文字がbufferに格納されている場合、null 終端記号は追加されず、負の値が返されます。If len > count, count characters are stored in buffer, no null-terminator is appended, and a negative value is returned.

Bufferが null ポインターで、 countが0の場合、出力の書式を設定するために必要な文字数としてlenが返されます。終端の null は含まれません。If buffer is a null pointer and count is zero, len is returned as the count of characters required to format the output, not including the terminating null. 同じ引数ロケールのパラメーターを使用して呼び出しを成功させるには、少なくともlen + 1 文字を保持するバッファーを割り当てます。To make a successful call with the same argument and locale parameters, allocate a buffer holding at least len + 1 characters.

Bufferが null ポインターで、 countが0以外の場合、またはformatが null ポインターの場合は、「パラメーターの検証」で説明されているように、無効なパラメーターハンドラーが呼び出されます。If buffer is a null pointer and count is nonzero, or if format is a null pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 実行の継続が許可された場合、これらの関数は-1 を返し、 errnoEINVALに設定します。If execution is allowed to continue, these functions return -1 and set errno to EINVAL.

エラー コードの詳細については、「errno、_doserrno、_sys_errlist、_sys_nerr」をご覧ください。For information about these and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

RemarksRemarks

Snprintf関数と _snprintf関数ファミリでは、バッファー内の文字を書式指定して格納します。The snprintf function and the _snprintf family of functions format and store count or fewer characters in buffer. Snprintf関数は、常に終端の null 文字を格納し、必要に応じて出力を切り捨てます。The snprintf function always stores a terminating null character, truncating the output if necessary. _Snprintfファミリの関数は、書式設定された文字列の長さが厳密にカウント文字未満の場合にのみ、終端の null 文字を追加します。The _snprintf family of functions only appends a terminating null character if the formatted string length is strictly less than count characters. 引数(存在する場合) は変換され、形式の対応する書式指定に従って出力されます。Each argument (if any) is converted and is 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. 重なり合う文字列間でコピーした場合の動作は未定義です。If copying occurs between strings that overlap, the behavior is undefined.

重要

format にユーザー定義の文字列を指定しないでください。Ensure that format is not a user-defined string. _Snprintf関数は null 終端処理を保証しないため (特に戻り値がcountの場合)、null 終端文字を追加するコードが続いていることを確認してください。Because the _snprintf functions do not guarantee null termination—in particular, when the return value is count—make sure that they are followed by code that adds the null terminator. 詳しくは、「 バッファー オーバーランの回避」をご覧ください。For more information, see Avoiding Buffer Overruns.

Visual Studio 2015 と Windows 10 の UCRT 以降では、 snprintf_snprintfと同じではなくなりました。Beginning with the UCRT in Visual Studio 2015 and Windows 10, snprintf is no longer identical to _snprintf. Snprintf関数の動作は、C99 標準に準拠するようになりました。The snprintf function behavior is now C99 standard compliant.

_snwprintfは、 _snprintfのワイド文字バージョンです。 _snwprintfへのポインター引数はワイド文字列です。_snwprintf is a wide-character version of _snprintf; the pointer arguments to _snwprintf are wide-character strings. _Snwprintfでのエンコードエラーの検出は、 _snprintfの場合とは異なる場合があります。Detection of encoding errors in _snwprintf might differ from that in _snprintf. _snwprintfは、 swprintfと同様に、出力を型ファイルの出力先ではなく文字列に書き込みます。_snwprintf, just like swprintf, writes output to a string instead of a destination of type FILE.

_Lサフィックスが付いているこれらの関数のバージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメーターを使用する点を除いて同じです。The versions of these functions that have the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、より安全な新しいバージョンを呼び出します。In C++, these functions have template overloads that invoke their newer, more secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

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

Tchar.h のルーチンTchar.h routine _UNICODE および _MBCS が未定義の場合_UNICODE and _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
sntprintf (_d)_sntprintf _snprintf_snprintf _snprintf_snprintf _snwprintf_snwprintf
sntprintf_l (_d)_sntprintf_l _snprintf_l_snprintf_l _snprintf_l_snprintf_l _snwprintf_l_snwprintf_l

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
snprintf_snprintf、およびsnprintf_lsnprintf, _snprintf, _snprintf_l <stdio.h><stdio.h>
_snwprintfsnwprintf_l_snwprintf, _snwprintf_l <stdio.h> または <wchar.h><stdio.h> or <wchar.h>

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

Example

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

関連項目See also

ストリーム入出力Stream I/O
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf、_fprintf_l、fwprintf、_fwprintf_lfprintf, _fprintf_l, fwprintf, _fwprintf_l
printf、_printf_l、wprintf、_wprintf_lprintf, _printf_l, wprintf, _wprintf_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