strncat_s
, _strncat_s_l
, wcsncat_s
, _wcsncat_s_l
, _mbsncat_s
, _mbsncat_s_l
文字列に文字を追加します。 これらのバージョンの , , , , _wcsncat_l
_mbsncat_l
_mbsncat
には、CRT のセキュリティ機能に関する説明に従って、セキュリティが強化されています。 wcsncat
_strncat_l
strncat
重要
_mbsncat_s
および _mbsncat_s_l
は、Windows ランタイムで実行するアプリケーションでは使用できません。 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない CRT 関数」を参照してください。
構文
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
パラメーター
strDest
NULL で終わる追加先の文字列。
numberOfElements
コピー先のバッファーのサイズ。
strSource
NULL で終わる元の文字列。
count
追加する文字数、または _TRUNCATE
.
locale
使用するロケール。
戻り値
正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。
エラー条件
strDestination |
numberOfElements |
strSource |
戻り値 | strDestination の内容 |
---|---|---|---|---|
NULL または終端文字なし |
any | any | EINVAL |
変更されない |
any | any | NULL |
EINVAL |
変更されない |
any | 0 または小さすぎる | any | ERANGE |
変更されない |
解説
これらの関数は、D
の最初の strSource
文字を strDest
の末尾に追加しようとします。このとき、D
は count
より小さく、strSource
の長さになります。 これらのD
文字を追加すると (サイズがnumberOfElements
指定された) 内にstrDest
収まり、null ターミネータ用の領域が残っている場合、それらの文字は、元のstrDest
終端の null から始まり、新しい終端の null が追加されます。それ以外の場合は、null 文字に設定され、strDest[0]
パラメーターの検証で説明されているように無効なパラメーター ハンドラーが呼び出されます。
上記の段落には例外があります。 ある場合 count
は _TRUNCATE
、収まる限り多く strSource
が追加され strDest
、終端の null を追加する余地が残ります。
たとえば、 にします。
char dst[5];
strncpy_s(dst, _countof(dst), "12", 2);
strncat_s(dst, _countof(dst), "34567", 3);
は、バッファー内の 2 文字に 5 文字の長さに 3 文字を追加することを求めている strncat_s
ことを意味します。null 終端記号のスペースが残らないので strncat_s
、文字列がゼロになり、無効なパラメーター ハンドラーが呼び出されます。
切り捨て動作が必要な場合は、次のように、_TRUNCATE
を使用するか、適宜、count
を調整します。
strncat_s(dst, _countof(dst), "34567", _TRUNCATE);
または
strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);
結果の文字列はすべて、null 文字で終了します。 重なり合う文字列間でコピーした場合の動作は未定義です。
strDest
または 0 の場合strSource
、「numberOfElements
NULL
パラメーターの検証」で説明されているように、無効なパラメーター ハンドラーが呼び出されます。 実行の継続が許可された場合、パラメーターを変更することなく、関数は EINVAL
を返します。
wcsncat_s
関数と _mbsncat_s
関数は、strncat_s
関数のワイド文字バージョンとマルチバイト文字バージョンです。 文字列引数と戻り値 wcsncat_s
はワイド文字列です。 引数と戻り値 _mbsncat_s
はマルチバイト文字列です。 それ以外では、これらの関数の動作は同じです。
出力値は、ロケールの LC_CTYPE
カテゴリ設定の設定によって影響を受けます。 詳細については、setlocale
を参照してください。 サフィックスのない _l
これらの関数のバージョンでは、このロケールに依存する動作に現在のロケールが使用されます。サフィックスを持つ _l
バージョンは、代わりに渡されたロケール パラメーターを使用する点が異なります。 詳細については、「 Locale」を参照してください。
C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。 詳細については、「セキュリティで保護されたテンプレート オーバーロード」を参照してください。
これらの関数のデバッグ ライブラリ バージョンでは、最初にバッファーを 0xFE で埋めます。 この動作を無効にするには、_CrtSetDebugFillThreshold
を使用します。
既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT のグローバル状態」を参照してください。
汎用テキスト ルーチンのマップ
TCHAR.H のルーチン | _UNICODE と _MBCS が定義されていない |
_MBCS が定義されている |
_UNICODE が定義されている |
---|---|---|---|
_tcsncat_s |
strncat_s |
_mbsnbcat_s |
wcsncat_s |
_tcsncat_s_l |
_strncat_s_l |
_mbsnbcat_s_l |
_wcsncat_s_l |
_strncat_s_l
ロケール _wcsncat_s_l
に依存 _tcsncat_s_l
しません。
必要条件
ルーチンによって返される値 | 必須ヘッダー |
---|---|
strncat_s |
<string.h> |
wcsncat_s |
<string.h> または <wchar.h> |
_mbsncat_s , _mbsncat_s_l |
<mbstring.h> |
互換性の詳細については、「 Compatibility」を参照してください。
例
// 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: ''
関連項目
文字列操作
ロケール
マルチバイト文字シーケンスの解釈
_mbsnbcat
, _mbsnbcat_l
strcat
, wcscat
, _mbscat
strcmp
, wcscmp
, _mbscmp
strcpy
, wcscpy
, _mbscpy
strncmp
, wcsncmp
, _mbsncmp
, _mbsncmp_l
strncpy
, _strncpy_l
, wcsncpy
, _wcsncpy_l
, _mbsncpy
, _mbsncpy_l
_strnicmp
, _wcsnicmp
, _mbsnicmp
, _strnicmp_l
, _wcsnicmp_l
, _mbsnicmp_l
strrchr
, wcsrchr
, _mbsrchr
, _mbsrchr_l
_strset
, _strset_l
, _wcsset
, _wcsset_l
, _mbsset
, _mbsset_l
strspn
, wcsspn
, _mbsspn
, _mbsspn_l
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示