strcpy_s，wcscpy_s _mbscpy_s

發行項
03/26/2013

複製資料。這些是 strcpy， wcscpy， _mbscpy 的安全性增強版本，如安全性功能，則在 CRT 中中所述。

重要

_mbscpy_s 不能用於 Windows 執行階段執行的應用程式。如需詳細資訊，請參閱 CRT 函式不支援使用 /ZW。

errno_t strcpy_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscpy_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscpy_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcpy_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

參數

strDestination
位置字串緩衝區
numberOfElements
目的資料緩衝區的大小。
strSource
innull 結尾字串的來源緩衝區。

傳回值

零，如果成功;否則為 false。

錯誤情況

strDestination	numberOfElements	strSource	傳回值	strDestination的內容。
NULL	any	any	EINVAL	無法修改
any	any	NULL	EINVAL	strDestination[0 個] 設定為 0
any	0、太小	any	ERANGE	strDestination[0 個] 設定為 0

備註

strcpy_s 函式會複製 strSource位址的內容，包括結束的 null 字元，為 strDestination指定的位置。目的資料必須夠大保留來源字串，包括結束的 null 字元。如果來源和目的資料重疊， strcpy_s 行為是未定義。

wcscpy_s 和 _mbscpy_s 分別為 strcpy_s 寬字元和多位元組字元版本。引數和傳回值 wcscpy_s 為寬字串;這些 _mbscpy_s 是多位元組字元字串。這三個函式其餘部分的運作相同。

如果 strDestination 或 strSource 為 null 指標，則為，如果目的字串太小，無效的參數處理常式叫用如參數驗證中所述。如果執行允許繼續執行，這些函式傳回 EINVAL 並將 errno 設為 EINVAL。

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

在 C++ 中，使用這些函式由範本多載簡化;多載會推斷緩衝區長度 (自動排除指定大小引數)，也可以用它們較新，安全對應自動取代舊，不安全的函式。如需詳細資訊，請參閱安全範本多載。

這些函式的偵錯版本 0xFE 先填入緩衝區。若要停用此行為，請使用 _CrtSetDebugFillThreshold 。

泛用文字常式對應

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>

如需其他相容性資訊，請參閱入門介紹中的相容性 (Compatibility) 。

範例

// crt_strcpy_s.cpp
// This program uses strcpy_s and strcat_s
// to build a phrase.
//

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

int main( void )
{
   char string[80];
   // using template versions of strcpy_s and strcat_s:
   strcpy_s( string, "Hello world from " );
   strcat_s( string, "strcpy_s " );
   strcat_s( string, "and " );
   // of course we can supply the size explicitly if we want to:
   strcat_s( string, _countof(string), "strcat_s!" );
   
   printf( "String = %s\n", string );
}