Fungsi lstrcpynA (winbase.h)

Artikel
03/08/2023

Menyalin sejumlah karakter tertentu dari string sumber ke dalam buffer.

Peringatan Jangan gunakan. Pertimbangkan untuk menggunakan StringCchCopy sebagai gantinya. Lihat Keterangan.

Sintaks

LPSTR lstrcpynA(
  [out] LPSTR  lpString1,
  [in]  LPCSTR lpString2,
  [in]  int    iMaxLength
);

Parameter

[out] lpString1

Jenis: LPTSTR

Buffer tujuan, yang menerima karakter yang disalin. Buffer harus cukup besar untuk berisi jumlah nilai TCHAR yang ditentukan oleh iMaxLength, termasuk ruang untuk karakter null yang mengakhiri.

[in] lpString2

Jenis: LPCTSTR

String sumber dari mana fungsi adalah menyalin karakter.

[in] iMaxLength

Jenis: int

Jumlah nilai TCHAR yang akan disalin dari string yang diacu oleh lpString2 ke dalam buffer yang diacu oleh lpString1, termasuk karakter null yang mengakhiri.

Nilai kembali

Jenis: LPTSTR

Jika fungsi berhasil, nilai yang dikembalikan adalah penunjuk ke buffer. Fungsi ini dapat berhasil meskipun string sumber lebih besar dari karakter iMaxLength .

Jika fungsi gagal, nilai yang dikembalikan adalah NULL dan lpString1 mungkin tidak dihentikan null.

Keterangan

Buffer yang ditujukkan oleh lpString1 harus cukup besar untuk menyertakan karakter null yang mengakhiri, dan nilai panjang string yang ditentukan oleh iMaxLength menyertakan ruang untuk karakter null yang mengakhiri.

Fungsi lstrcpyn memiliki perilaku yang tidak terdefinisi jika buffer sumber dan tujuan tumpang tindih.

Peringatan Keamanan

Menggunakan fungsi ini salah dapat membahayakan keamanan aplikasi Anda. Fungsi ini menggunakan penanganan pengecualian terstruktur (SEH) untuk menangkap pelanggaran akses dan kesalahan lainnya. Ketika fungsi ini menangkap kesalahan SEH, fungsi ini mengembalikan NULL tanpa menghentikan string null dan tanpa memberi tahu pemanggil kesalahan. Pemanggil tidak aman untuk mengasumsikan bahwa ruang yang tidak mencukup adalah kondisi kesalahan.

Jika buffer yang ditujukkan oleh lpString1 tidak cukup besar untuk berisi string yang disalin, overrun buffer dapat terjadi. Saat menyalin seluruh string, perhatikan bahwa ukuranof mengembalikan jumlah byte. Misalnya, jika lpString1 menunjuk ke buffer szString1 yang dinyatakan sebagai TCHAR szString[100], maka sizeof(szString1) memberikan ukuran buffer dalam byte daripada WCHAR, yang dapat menyebabkan luapan buffer untuk versi Unicode fungsi.

Situasi luapan buffer adalah penyebab banyak masalah keamanan dalam aplikasi dan dapat menyebabkan penolakan serangan layanan terhadap aplikasi jika pelanggaran akses terjadi. Dalam kasus terburuk, buffer overrun dapat memungkinkan penyerang untuk menyuntikkan kode yang dapat dieksekusi ke dalam proses Anda, terutama jika lpString1 adalah buffer berbasis tumpukan.

Menggunakan sizeof(szString1)/sizeof(szString1[0]) memberikan ukuran buffer yang tepat.

Pertimbangkan untuk menggunakan StringCchCopy sebagai gantinya; gunakan , StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src);menyadari bahwa buffer tidak boleh menjadi penunjuk atau menggunakan StringCchCopy(buffer, ARRAYSIZE(buffer), src);, menyadari bahwa, saat menyalin ke penunjuk, pemanggil bertanggung jawab untuk meneruskan ukuran memori yang diarahkan ke karakter.

Tinjau Pertimbangan Keamanan: Antarmuka Pengguna Windows sebelum melanjutkan.

Catatan

Header winbase.h mendefinisikan lstrcpyn sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll