strcpy_s、 wcscpy_s、 _mbscpy_s、 _mbscpy_s_l

文字列をコピーします。 これらのバージョンの strcpy、 wcscpy、 _mbscpy には、CRT の セキュリティ機能の説明に従ってセキュリティが強化。

重要

_mbscpy_s および _mbscpy_s_l は、Windows ランタイムで実行するアプリケーションでは使用できません。 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない CRT 関数」を参照してください。

構文

errno_t strcpy_s(
   char *dest,
   rsize_t dest_size,
   const char *src
);
errno_t wcscpy_s(
   wchar_t *dest,
   rsize_t dest_size,
   const wchar_t *src
);
errno_t _mbscpy_s(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src
);
errno_t _mbscpy_s_l(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src,
   _locale_t locale
);

// Template functions are C++ only:
template <size_t size>
errno_t strcpy_s(
   char (&dest)[size],
   const char *src
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&dest)[size],
   const wchar_t *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&dest)[size],
   const unsigned char *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s_l(
   unsigned char (&dest)[size],
   const unsigned char *src,
   _locale_t locale
); // C++ only

パラメーター

dest
追加先の文字列バッファーの場所。

dest_size
ナロー関数とマルチバイト関数の場合は、コピー先の文字列バッファーの char 単位のサイズ、ワイド関数の場合は wchar_t 単位のサイズ。 この値は 0 より大きく、RSIZE_MAX より大きくない必要があります。 このサイズに、文字列の後に続く終端の NULL を含めるようにします。

src
null で終わる元の文字列バッファー。

locale
使用するロケール。

戻り値

正常に終了した場合は 0 を返し、それ以外の場合はエラーを返します。

エラー条件

dest	dest_size	src	戻り値	dest の内容
NULL	任意	任意	EINVAL	変更されない
任意	任意	NULL	EINVAL	0 に設定された dest[0]
任意	0 または小さすぎる	任意	ERANGE	0 に設定された dest[0]

解説

strcpy_s 関数は、src のアドレスの内容を、終端の NULL 文字も含めて、dest で指定された場所にコピーします。 コピー先の文字列には、コピー元の文字列とその終端の NULL 文字を保持できるサイズが必要です。 コピー元とコピー先の文字列が重なり合っている場合の strcpy_s 関数の動作は未定義です。

wcscpy_s は strcpy_s のワイド文字バージョンであり、_mbscpy_s はマルチバイト文字バージョンです。 wcscpy_sの引数はワイド文字列です。 _mbscpy_sと_mbscpy_s_lの引数はマルチバイト文字列です。 それ以外では、これらの関数の動作は同じです。 _mbscpy_s_l は、現在のロケールの代わりに、渡されたロケール パラメーターを使用する点を除き、_mbscpy_s と同じです。 詳細については、localeを参照してください。

destまたはsrcが null ポインターの場合、またはコピー先の文字列サイズdest_sizeが小さすぎる場合は、「パラメーターの検証」で説明されているように、無効なパラメーター ハンドラーが呼び出されます。 実行の継続が許可された場合、EINVAL または errno が NULL ポインターならば、これらの関数は EINVAL を返し、dest を src に設定します。コピー先の文字列が小さすぎると、ERANGE を返し、errno を ERANGE に設定します。

正常に実行されると、コピー先の文字列は常に NULL で終わります。

C++ では、これらの関数の使用は、バッファー長を自動的に推論できるテンプレート オーバーロードによって簡略化されるため、サイズ引数を指定する必要はありません。 また、古くて安全性の低い関数を、より新しい、より安全な関数に自動的に置き換えることができます。 詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。

これらの関数のデバッグ ライブラリ バージョンでは、最初にバッファーを 0xFE で埋めます。 この動作を無効にするには、_CrtSetDebugFillThreshold を使用します。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

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

TCHAR.H ルーチン	_UNICODE と _MBCS が定義されていない	_MBCS が定義されている	_UNICODE が定義されている
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

要件

ルーチンによって返される値	必須ヘッダー
strcpy_s	<string.h>
wcscpy_s	<string.h> または <wchar.h>
_mbscpy_s	<mbstring.h>

これらの関数は Microsoft 固有です。 互換性の詳細については、「 Compatibility」を参照してください。

例

運用品質コードとは異なり、このサンプルでは、エラーをチェックせずに、セキュリティで保護された文字列関数を呼び出します。

// crt_strcpy_s.c
// Compile by using: cl /W4 crt_strcpy_s.c
// This program uses strcpy_s and strcat_s
// to build a phrase.

#include <string.h>     // for strcpy_s, strcat_s
#include <stdlib.h>     // for _countof
#include <stdio.h>      // for printf
#include <errno.h>      // for return values

int main(void)
{
    char stringBuffer[80];

    strcpy_s(stringBuffer, _countof(stringBuffer), "Hello world from ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcpy_s ");
    strcat_s(stringBuffer, _countof(stringBuffer), "and ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcat_s!");

    printf("stringBuffer = %s\n", stringBuffer);
}

stringBuffer = Hello world from strcpy_s and strcat_s!

C++ コードをビルドする場合は、テンプレートのバージョンを使用する方が簡単な場合があります。

// crt_wcscpy_s.cpp
// Compile by using: cl /EHsc /W4 crt_wcscpy_s.cpp
// This program uses wcscpy_s and wcscat_s
// to build a phrase.

#include <cstring>  // for wcscpy_s, wcscat_s
#include <cstdlib>  // for _countof
#include <iostream> // for cout, includes <cstdlib>, <cstring>
#include <errno.h>  // for return values

int main(void)
{
    wchar_t stringBuffer[80];
    // using template versions of wcscpy_s and wcscat_s:
    wcscpy_s(stringBuffer, L"Hello world from ");
    wcscat_s(stringBuffer, L"wcscpy_s ");
    wcscat_s(stringBuffer, L"and ");
    // of course we can supply the size explicitly if we want to:
    wcscat_s(stringBuffer, _countof(stringBuffer), L"wcscat_s!");

    std::wcout << L"stringBuffer = " << stringBuffer << std::endl;
}

stringBuffer = Hello world from wcscpy_s and wcscat_s!

関連項目

文字列操作
strcat、 wcscat、 _mbscat、 _mbscat_l
strcmp、 wcscmp、 _mbscmp、 _mbscmp_l
strncat_s、 _strncat_s_l、 wcsncat_s、 _wcsncat_s_l、 _mbsncat_s、 _mbsncat_s_l
strncmp、 wcsncmp、 _mbsncmp、 _mbsncmp_l
strncpy_s、 _strncpy_s_l、 wcsncpy_s、 _wcsncpy_s_l、 _mbsncpy_s、 _mbsncpy_s_l
_strnicmp、 _wcsnicmp、 _mbsnicmp、 _strnicmp_l、 _wcsnicmp_l、 _mbsnicmp_l
strrchr、 wcsrchr、 _mbsrchr、 _mbsrchr_l
strspn、 wcsspn、 _mbsspn、 _mbsspn_l