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 内容strDestinationContents of strDestination
NULLまたは終端文字なしNULL or unterminated 任意any 任意any EINVALEINVAL 変更されないnot modified
任意any 任意any NULLNULL EINVALEINVAL 変更されないnot modified
任意any 0 または小さすぎる0, or too small 任意any ERANGEERANGE 変更されないnot modified

RemarksRemarks

これらの関数が、最初に追加しようとしていますDの文字strSourceの末尾に追加される文字ここで、 D のうちの小さい方が 。カウントの長さと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. 追加された場合はD内に収まる文字追加される文字(としてサイズが指定されてnumberOfElements) し、null 終端記号をこれらの文字の余裕と追加すると、元の null の終端から始まる追加される文字、新しい終端の null は追加されるそれ以外と追加される文字[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. 場合_TRUNCATEだけの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);

確認していることを意味strncat_sバッファー 5 の 2 つの文字に 3 つの文字を追加する文字の長い; これは余裕がありません、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);

またはor

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または追加される文字NULL、または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_sのワイド文字とマルチバイト文字バージョンstrncat_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. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

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

汎用テキスト ルーチンのマップ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