strcpy_s、 、 wcscpy_s、 _mbscpy_s_mbscpy_s_l

複製字串。 這些版本的strcpy、 wcscpy _mbscpy具有安全性增強功能，如 CRT 的安全性功能中所述。

重要

在 Windows 執行階段中執行的應用程式中無法使用 _mbscpy_s 和 _mbscpy_s_l。 如需詳細資訊，請參閱 CRT functions not supported in Universal Windows Platform apps (通用 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 為單位。 這個值必須大於零，而不是大於 RSIZE_MAX。 請確定此大小是字串之後終止 NULL 的帳戶。

src
以 null 結束的來源字串緩衝區。

locale
要使用的地區設定。

傳回值

如果成功則為零，否則為錯誤。

錯誤條件

dest	dest_size	src	傳回值	dest 的內容。
NULL	任意	任意	EINVAL	未修改
任意	任意	NULL	EINVAL	dest[0] 設定為 0
任意	0 或太小	任意	ERANGE	dest[0] 設定為 0

備註

strcpy_s 函式會將 src 位址中的內容 (包含結束的 null 字元) 複製到 dest 所指定的位置。 目的字串必須大到足以保留來源字串及其結束的 null 字元。 如果來源和目的字串重疊，則 strcpy_s 的行為未定義。

wcscpy_s 是 strcpy_s 的寬字元版本，而 _mbscpy_s 則是多位元組字元版本。 的自變數 wcscpy_s 是寬字元字串。 和 _mbscpy_s_l 的_mbscpy_s自變數是多位元組位元元字串。 除此之外，這些函式的行為相同。 _mbscpy_s_l 與 _mbscpy_s 相同，不同之處在於它會使用傳入的地區設定參數，而不是目前的地區設定。 如需詳細資訊，請參閱locale。

如果 dest 或 src 為 Null 指標，或目的地字串大小dest_size太小，則會叫用無效的參數處理程式，如參數驗證中所述。 如果允許繼續執行，當 dest 或 src 為 null 指標時，這些函式會傳回 EINVAL 並將 errno 設為 EINVAL，當目的字串太小時，這些函式會傳回 ERANGE 並將 errno 設為 ERANGE。

成功執行後，目的字串永遠是以 null 終止的。

在C++中，範本多載可以自動推斷緩衝區長度的範本多載可簡化這些函式的使用，因此您不需要指定 size 自變數。 而且，他們可以使用較新的、更安全的對應專案來自動取代較舊、較不安全的函式。 如需詳細資訊，請參閱安全範本多載。

這些函式的偵錯連結庫版本會先將緩衝區填入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特定。 如需相容性詳細資訊，請參閱相容性。

範例

不同於生產品質程序代碼，此範例會呼叫安全字串函式，而不檢查錯誤：

// 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_lwcsncat_s、_wcsncat_s_l、、_mbsncat_s、_mbsncat_s_l
strncmp、 、 wcsncmp、 _mbsncmp_mbsncmp_l
strncpy_s、、_strncpy_s_lwcsncpy_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