strcpy_s、wcscpy_s、_mbscpy_s、_mbscpy_s_lstrcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

文字列をコピーします。Copies a string. これらのバージョンの strcpy、wcscpy、_mbscpy は、「CRT のセキュリティ機能」の説明にあるとおり、セキュリティが強化されました。These versions of strcpy, wcscpy, _mbscpy have security enhancements, as described in Security Features in the CRT.

重要

_mbscpy_s_mbscpy_s_l Windows ランタイムで実行するアプリケーションでは使用できません。_mbscpy_s and _mbscpy_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 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

パラメーターParameters

destdest
追加先の文字列バッファーの場所。Location of the destination string buffer.

dest_sizedest_size
変換先文字列バッファーのサイズchar狭いおよびマルチバイト関数でのユニットとwchar_tワイド関数の単位。Size of the destination string buffer in char units for narrow and multi-byte functions, and wchar_t units for wide functions. この値は 0 より大きいとより大きくないありますRSIZE_MAXします。This value must be greater than zero and not greater than RSIZE_MAX.

srcsrc
null で終わる元の文字列バッファー。Null-terminated source string buffer.

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

戻り値Return Value

正常に終了した場合は 0 を返し、それ以外の場合はエラーを返します。Zero if successful; otherwise, an error.

エラー条件Error Conditions

destdest dest_sizedest_size srcsrc 戻り値Return value 内容destContents of dest
NULLNULL 任意any 任意any EINVALEINVAL 変更されないnot modified
任意any 任意any NULLNULL EINVALEINVAL dest[0] が 0 に設定dest[0] set to 0
任意any 0 または小さすぎる0, or too small 任意any ERANGEERANGE dest[0] が 0 に設定dest[0] set to 0

RemarksRemarks

Strcpy_s関数のアドレスの内容をコピーするsrcで指定された場所に、終端の null 文字を含むdestします。The strcpy_s function copies the contents in the address of src, including the terminating null character, to the location that's specified by dest. コピー先の文字列には、コピー元の文字列とその終端の NULL 文字を保持できるサイズが必要です。The destination string must be large enough to hold the source string and its terminating null character. 動作strcpy_s元とコピー先文字列が重なり合う場合は定義されません。The behavior of strcpy_s is undefined if the source and destination strings overlap.

wcscpy_sのワイド文字バージョンは、 strcpy_s、および _mbscpy_sマルチバイト文字バージョンです。wcscpy_s is the wide-character version of strcpy_s, and _mbscpy_s is the multibyte-character version. 引数wcscpy_sはワイド文字列 _mbscpy_s_mbscpy_s_lはマルチバイト文字の文字列。The arguments of wcscpy_s are wide-character strings; those of _mbscpy_s and _mbscpy_s_l are multibyte-character strings. それ以外では、これらの関数の動作は同じです。These functions behave identically otherwise. _mbscpy_s_lヲェヒェケェ ・ _mbscpy_sを現在のロケールの代わりに渡されたロケール パラメーターを使用します。_mbscpy_s_l is identical to _mbscpy_s except that it uses the locale parameter passed in instead of the current locale. 詳細については、「 Locale」を参照してください。For more information, see Locale.

場合destまたはsrcが null ポインターの場合は、変換先の文字列サイズまたはdest_size 」の説明に従って、小さすぎる、無効なパラメーターハンドラーが呼び出されますがパラメーターの検証です。If dest or src is a null pointer, or if the destination string size dest_size is too small, the invalid parameter handler is invoked, as described in Parameter Validation. これらの関数を返すかどうかは、引き続き実行が許可された、 EINVAL設定とerrnoEINVALときdestまたはsrc null ポインターの場合は、返されるERANGE設定とerrnoERANGEコピー先文字列が小さすぎる場合。If execution is allowed to continue, these functions return EINVAL and set errno to EINVAL when dest or src is a null pointer, and they return ERANGE and set errno to ERANGE when the destination string is too small.

正常に実行されると、コピー先の文字列は常に NULL で終わります。Upon successful execution, the destination string is always null-terminated.

C++ では、これらの関数をより簡単に使用できます。これはバッファー長を自動的に推論できるテンプレートのオーバーロードにより可能です。その結果、サイズの引数を指定する必要がなくなります。また、セキュリティが万全ではない以前の関数は、セキュリティが強化された新しい関数に自動的に置き換わります。In C++, use of these functions is simplified by template overloads that can infer buffer length automatically so that you don't have to specify a size argument, and they can automatically replace older, less-secure functions with their newer, more secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

これらの関数のデバッグ ライブラリのバージョンは、最初にバッファーを 0 xfe を埋めます。The debug library versions of these functions first fill the buffer with 0xFE. この動作を無効にするには、_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
_tcscpy_s_tcscpy_s strcpy_sstrcpy_s _mbscpy_s_mbscpy_s wcscpy_swcscpy_s

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
strcpy_sstrcpy_s <string.h><string.h>
wcscpy_swcscpy_s <string.h> または <wchar.h><string.h> or <wchar.h>
_mbscpy_s_mbscpy_s <mbstring.h><mbstring.h>

これらの関数は、Microsoft 固有です。These functions are Microsoft-specific. 互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

運用環境品質のコードとは異なり、このサンプルは、エラーをチェックせず、セキュリティで保護された文字列関数を呼び出します。Unlike production quality code, this sample calls the secure string functions without checking for errors:

// 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 string[80];

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

    printf("String = %s\n", string);
}
String = Hello world from strcpy_s and strcat_s!

C++ コードを作成するときに、テンプレートのバージョンが使いやすい可能性があります。When building C++ code, the template versions may be easier to use.

// 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 string[80];
    // using template versions of wcscpy_s and wcscat_s:
    wcscpy_s(string, L"Hello world from ");
    wcscat_s(string, L"wcscpy_s ");
    wcscat_s(string, L"and ");
    // of course we can supply the size explicitly if we want to:
    wcscat_s(string, _countof(string), L"wcscat_s!");

    std::wcout << L"String = " << string << std::endl;
}
String = Hello world from wcscpy_s and wcscat_s!

関連項目See also

文字列操作String Manipulation
strcat、wcscat、_mbscat、_mbscat_lstrcat, wcscat, _mbscat, _mbscat_l
strcmp、wcscmp、_mbscmp、_mbscmp_lstrcmp, wcscmp, _mbscmp, _mbscmp_l
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
strncmp、wcsncmp、_mbsncmp、_mbsncmp_lstrncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy_s、_strncpy_s_l、wcsncpy_s、_wcsncpy_s_l、_mbsncpy_s、_mbsncpy_s_lstrncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_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
strspn、wcsspn、_mbsspn、_mbsspn_lstrspn, wcsspn, _mbsspn, _mbsspn_l