strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Menyalin string. Versi strcpy, , _mbscpywcscpyini memiliki peningkatan keamanan, seperti yang dijelaskan dalam Fitur keamanan di CRT.

Penting

_mbscpy_s dan _mbscpy_s_l tidak dapat digunakan dalam aplikasi yang dijalankan di Windows Runtime. Untuk informasi selengkapnya, lihat Fungsi CRT yang tidak didukung di aplikasi Platform Windows Universal.

Sintaks

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

Parameter

dest
Lokasi buffer string tujuan.

dest_size
Ukuran buffer string tujuan dalam char unit untuk fungsi sempit dan multi-byte, dan wchar_t unit untuk fungsi yang luas. Nilai ini harus lebih besar dari nol dan tidak lebih besar dari RSIZE_MAX. Pastikan ukuran ini menyumbang penghentian NULL setelah string.

src
Buffer string sumber yang dihentikan null.

locale
Lokal untuk digunakan.

Nilai hasil

Nol jika berhasil; jika tidak, kesalahan.

Kondisi kesalahan

dest	dest_size	src	Nilai hasil	Isi dari dest
NULL	any	any	EINVAL	tidak dimodifikasi
any	any	NULL	EINVAL	dest[0] atur ke 0
any	0, atau terlalu kecil	any	ERANGE	dest[0] atur ke 0

Keterangan

Fungsi strcpy_s menyalin konten dalam alamat src, termasuk mengakhiri karakter null, ke lokasi yang ditentukan oleh dest. String tujuan harus cukup besar untuk menahan string sumber dan karakter null yang berakhir. Perilaku strcpy_s tidak terdefinisi jika string sumber dan tujuan tumpang tindih.

wcscpy_s adalah versi karakter luas dari strcpy_s, dan _mbscpy_s merupakan versi multibyte-character. Argumen adalah wcscpy_s string karakter lebar. Argumen dan _mbscpy_s_mbscpy_s_l adalah string multibyte-character. Fungsi-fungsi ini berulah secara identik jika tidak. _mbscpy_s_l identik dengan _mbscpy_s kecuali bahwa ia menggunakan parameter lokal yang diteruskan alih-alih lokal saat ini. Untuk informasi selengkapnya, lihat locale .

Jika dest atau src adalah penunjuk null, atau jika ukuran dest_size string tujuan terlalu kecil, handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, fungsi-fungsi ini kembali EINVAL dan diatur errno ke EINVAL kapan dest atau src adalah penunjuk null, dan mereka kembali ERANGE dan diatur errno ke ERANGE ketika string tujuan terlalu kecil.

Setelah eksekusi berhasil, string tujuan selalu dihentikan null.

Di C++, penggunaan fungsi-fungsi ini disederhanakan oleh kelebihan beban templat yang dapat menyimpulkan panjang buffer secara otomatis, sehingga Anda tidak perlu menentukan argumen ukuran. Dan, mereka dapat secara otomatis mengganti fungsi yang lebih lama dan kurang aman dengan rekan-rekan yang lebih baru dan lebih aman. Untuk informasi selengkapnya, lihat Mengamankan kelebihan beban templat.

Versi pustaka debug dari fungsi-fungsi ini terlebih dahulu mengisi buffer dengan 0xFE. Untuk menonaktifkan perilaku ini, gunakan _CrtSetDebugFillThreshold.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Pemetaan rutin teks generik

TCHAR.H Rutin	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Persyaratan

Rutin	Header yang diperlukan
strcpy_s	<string.h>
wcscpy_s	<string.h> atau <wchar.h>
_mbscpy_s	<mbstring.h>

Fungsi-fungsi ini khusus Microsoft. Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

Tidak seperti kode kualitas produksi, sampel ini memanggil fungsi string aman tanpa memeriksa kesalahan:

// 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!

Saat Anda membuat kode C++, versi templat mungkin lebih mudah digunakan.

// 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!

Baca juga

Manipulasi string
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