strncat_s、_strncat_s_l、wcsncat_s、_wcsncat_s_l、_mbsncat_s、_mbsncat_s_lstrncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

文字列に文字を追加します。Appends characters to a string. これらのバージョンの strncat、_strncat_l、wcsncat、_wcsncat_l、_mbsncat、_mbsncat_l は、「CRT のセキュリティ機能」にあるとおり、セキュリティが強化されています。These versions of strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l have security enhancements, as described in Security Features in the CRT.

重要

_mbsncat_s_mbsncat_s_lは、Windows ランタイムで実行されるアプリケーションでは使用できません。_mbsncat_s and _mbsncat_s_l cannot be used in applications that execute in the Windows Runtime. 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない CRT 関数」を参照してください。For more information, see CRT functions not supported in Universal Windows Platform apps.

構文Syntax

errno_t strncat_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncat_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncat_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count
);
errno_t _wcsncat_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncat_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncat_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncat_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncat_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncat_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _wcsncat_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncat_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncat_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

パラメーターParameters

strDeststrDest
NULL で終わる追加先の文字列。Null-terminated destination string.

numberOfElementsnumberOfElements
コピー先のバッファーのサイズ。Size of the destination buffer.

strSourcestrSource
NULL で終わる元の文字列。Null-terminated source string.

countcount
追加する文字数、または _TRUNCATENumber of characters to append, or _TRUNCATE.

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

戻り値Return Value

正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。Returns 0 if successful, an error code on failure.

エラー条件Error Conditions

strDestinationstrDestination numberOfElementsnumberOfElements strSourcestrSource 戻り値Return value Strdestinationの内容Contents of strDestination
NULLまたは未終了NULL or unterminated anyany anyany EINVALEINVAL 変更されないnot modified
anyany anyany 空白NULL EINVALEINVAL 変更されないnot modified
anyany 0 または小さすぎる0, or too small anyany ERANGEERANGE 変更されないnot modified

解説Remarks

これらの関数は、 Strsourceの最初のD文字をstrsourceの末尾に追加しようとします。ここで、 dは、 countの小さい方、およびstrsourceの長さです。These functions try to append the first D characters of strSource to the end of strDest, where D is the lesser of count and the length of strSource. (サイズがNumberofelementsとして指定されている) strdestに収まるようにD文字を追加した後も、null 終端文字のスペースを残す場合は、これらの文字が追加され、 strdestの元の終端の null から開始し、新しい終端の null が追加されます。それ以外の場合、 Strdest[0] は null 文字に設定され、「パラメーターの検証」で説明されているように、無効なパラメーターハンドラーが呼び出されます。If appending those D characters will fit within strDest (whose size is given as numberOfElements) and still leave room for a null terminator, then those characters are appended, starting at the original terminating null of strDest, and a new terminating null is appended; otherwise, strDest[0] is set to the null character and the invalid parameter handler is invoked, as described in Parameter Validation.

これには例外があります。There is an exception to the above paragraph. Count_TRUNCATE場合は、に格納されるStrsourceの多くがstrsourceに追加されますが、終端の null を追加する余地は残ったままになります。If count is _TRUNCATE then as much of strSource as will fit is appended to strDest while still leaving room to append a terminating null.

たとえば、次のように入力します。For example,

char dst[5];
strncpy_s(dst, _countof(dst), "12", 2);
strncat_s(dst, _countof(dst), "34567", 3);

は、5文字のバッファー内の2文字に3文字を追加するstrncat_sを求めていることを意味します。この場合、null 終端文字にはスペースが残されないため、文字列をゼロにstrncat_sし、無効なパラメーターハンドラーを呼び出します。means that we are asking strncat_s to append three characters to two characters in a buffer five characters long; this would leave no space for the null terminator, hence strncat_s zeroes out the string and calls the invalid parameter handler.

切り捨て動作が必要な場合は、 _TRUNCATEを使用するか、それに応じてサイズパラメーターを調整します。If truncation behavior is needed, use _TRUNCATE or adjust the size parameter accordingly:

strncat_s(dst, _countof(dst), "34567", _TRUNCATE);

oror

strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);

結果の文字列はすべて、null 文字で終了します。In all cases, the resulting string is terminated with a null character. 重なり合う文字列間でコピーした場合の動作は未定義です。If copying takes place between strings that overlap, the behavior is undefined.

StrsourceまたはStrsourceNULLの場合、またはnumberofelementsが0の場合は、「パラメーターの検証」で説明されているように、無効なパラメーターハンドラーが呼び出されます。If strSource or strDest is NULL, or is numberOfElements is zero, the invalid parameter handler is invoked, as described in Parameter Validation . 実行の継続が許可された場合、関数はパラメーターを変更せずにEINVALを返します。If execution is allowed to continue, the function returns EINVAL without modifying its parameters.

wcsncat_s_mbsncat_sstrncat_sのワイド文字バージョンとマルチバイト文字バージョンです。wcsncat_s and _mbsncat_s are wide-character and multibyte-character versions of strncat_s. Wcsncat_sの文字列引数と戻り値はワイド文字列です。これらの _mbsncat_sはマルチバイト文字列です。The string arguments and return value of wcsncat_s are wide-character strings; those of _mbsncat_s are multibyte-character strings. それ以外では、これらの関数の動作は同じです。These three functions behave identically otherwise.

出力値は、ロケールの LC_CTYPE カテゴリの設定に影響されます。詳細については、「setlocale」を参照してください。The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. _l サフィックスが付いていないこれらの関数のバージョンでは、このロケールに依存する動作に現在のロケールを使用します。_l サフィックスが付いているバージョンは、渡されたロケール パラメーターを代わりに使用する点を除いて同じです。The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. 詳細については、「 Locale」を参照してください。For more information, see Locale.

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

これらの関数のデバッグライブラリバージョンは、最初にバッファーを0xFE で埋めます。The debug library versions of these functions first fill the buffer with 0xFE. この動作を無効にするには、_CrtSetDebugFillThreshold を使用します。To disable this behavior, use _CrtSetDebugFillThreshold.

既定では、この関数のグローバル状態はアプリケーションにスコープが設定されています。By default, this function's global state is scoped to the application. これを変更するには、「 CRT でのグローバル状態」を参照してください。To change this, see Global state in the CRT.

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

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tcsncat_s_tcsncat_s strncat_sstrncat_s _mbsnbcat_s_mbsnbcat_s wcsncat_swcsncat_s
_tcsncat_s_l_tcsncat_s_l _strncat_s_l_strncat_s_l _mbsnbcat_s_l_mbsnbcat_s_l _wcsncat_s_l_wcsncat_s_l

_strncat_s_l_wcsncat_s_lはロケールに依存しません。これらは _tcsncat_s_lに対してのみ提供されます。_strncat_s_l and _wcsncat_s_l have no locale dependence; they are only provided for _tcsncat_s_l.

必要条件Requirements

ルーチンRoutine 必須ヘッダーRequired header
strncat_sstrncat_s <string.h><string.h>
wcsncat_swcsncat_s <string.h> または <wchar.h><string.h> or <wchar.h>
_mbsncat_s_mbsncat_s_l_mbsncat_s, _mbsncat_s_l <mbstring.h><mbstring.h>

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

Example

// crt_strncat_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

errno_t strncat_s_tester( const char * initialDest,
                          const char * src,
                          int count )
{
   char dest[10];
   strcpy_s( dest, _countof(dest), initialDest );

   printf_s( "\n" );

   if ( count == _TRUNCATE )
      printf_s( "Appending '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf_s( "Appending %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   printf_s( "    old contents of dest: '%s'\n", dest );

   errno_t err = strncat_s( dest, _countof(dest), src, count );

   printf_s( "    new contents of dest: '%s'\n", dest );

   return err;
}

void Examples()
{
   strncat_s_tester( "hi ", "there", 4 );
   strncat_s_tester( "hi ", "there", 5 );
   strncat_s_tester( "hi ", "there", 6 );

   printf_s( "\nDestination buffer too small:\n" );
   strncat_s_tester( "hello ", "there", 4 );

   printf_s( "\nTruncation examples:\n" );

   errno_t err = strncat_s_tester( "hello ", "there", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncat_s_tester( "hello ", "!", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf_s( "\nSecure template overload example:\n" );

   char dest[10] = "cats and ";
   strncat( dest, "dachshunds", 15 );
   // With secure template overloads enabled (see #define
   // at top of file), the preceding line is replaced by
   //    strncat_s( dest, _countof(dest), "dachshunds", 15 );
   // Instead of causing a buffer overrun, strncat_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncat would
   // append "dachshunds" and overrun the dest buffer.
   printf_s( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function,
   const wchar_t* file,
   unsigned int line,
   uintptr_t pReserved)
{
   wprintf_s(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}
Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi ther'

Appending 5 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Appending 6 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Destination buffer too small:

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hello '
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Appending 'there' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello the'
    truncation did occur

Appending '!' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello !'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

関連項目See also

文字列操作String Manipulation
Locale
マルチバイト文字のシーケンスの解釈Interpretation of Multibyte-Character Sequences
_mbsnbcat、_mbsnbcat_l_mbsnbcat, _mbsnbcat_l
strcat、wcscat、_mbscatstrcat, wcscat, _mbscat
strcmp、wcscmp、_mbscmpstrcmp, wcscmp, _mbscmp
strcpy、wcscpy、_mbscpystrcpy, wcscpy, _mbscpy
strncmp、wcsncmp、_mbsncmp、_mbsncmp_lstrncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy、_strncpy_l、wcsncpy、_wcsncpy_l、_mbsncpy、_mbsncpy_lstrncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp、_wcsnicmp、_mbsnicmp、_strnicmp_l、_wcsnicmp_l、_mbsnicmp_l_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr、wcsrchr、_mbsrchr、_mbsrchr_lstrrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset、_strset_l、_wcsset、_wcsset_l、_mbsset、_mbsset_l_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn、wcsspn、_mbsspn、_mbsspn_lstrspn, wcsspn, _mbsspn, _mbsspn_l