strncpy_s
, , _strncpy_s_l
wcsncpy_s
, _wcsncpy_s_l
, _mbsncpy_s
, _mbsncpy_s_l
, _tcsncpy_s
, _tcsncpy_s_l
, , _tcsnccpy_s
,_tcsnccpy_s_l
Menyalin karakter dari satu string ke string lainnya. Versi , , wcsncpy
_strncpy_l
, _wcsncpy_l
, , _mbsncpy
, ini _mbsncpy_l
memiliki peningkatan keamanan, seperti yang dijelaskan dalam Fitur keamanan di CRT.strncpy
Penting
_mbsncpy_s
dan _mbsncpy_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.
Untuk _tcsnccpy_s
, _tcsnccpy_s_l
, _tcsnccpy_s
, dan _tcsnccpy_s_l
lihat Pemetaan fungsi Generik-teks.
Sintaks
errno_t strncpy_s(
char *strDest,
size_t numberOfElements,
const char *strSource,
size_t count
);
errno_t _strncpy_s_l(
char *strDest,
size_t numberOfElements,
const char *strSource,
size_t count,
_locale_t locale
);
errno_t wcsncpy_s(
wchar_t *strDest,
size_t numberOfElements,
const wchar_t *strSource,
size_t count
);
errno_t _wcsncpy_s_l(
wchar_t *strDest,
size_t numberOfElements,
const wchar_t *strSource,
size_t count,
_locale_t locale
);
errno_t _mbsncpy_s(
unsigned char *strDest,
size_t numberOfElements,
const unsigned char *strSource,
size_t count
);
errno_t _mbsncpy_s_l(
unsigned char *strDest,
size_t numberOfElements,
const unsigned char *strSource,
size_t count,
_locale_t locale
);
template <size_t size>
errno_t strncpy_s(
char (&strDest)[size],
const char *strSource,
size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
char (&strDest)[size],
const char *strSource,
size_t count,
_locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
wchar_t (&strDest)[size],
const wchar_t *strSource,
size_t count
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
wchar_t (&strDest)[size],
const wchar_t *strSource,
size_t count,
_locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
unsigned char (&strDest)[size],
const unsigned char *strSource,
size_t count
); // C++ only
template <size_t size>
errno_t _mbsncpy_s_l(
unsigned char (&strDest)[size],
const unsigned char *strSource,
size_t count,
_locale_t locale
); // C++ only
Parameter
strDest
String tujuan.
numberOfElements
Ukuran string tujuan, dalam karakter.
strSource
String sumber.
count
Jumlah karakter yang akan disalin, atau _TRUNCATE
.
locale
Lokal yang akan digunakan.
Nilai hasil
Nol jika berhasil, STRUNCATE
jika pemotongan terjadi, jika tidak, kode kesalahan.
Kondisi kesalahan
strDest |
numberOfElements |
strSource |
Nilai hasil | Isi dari strDest |
---|---|---|---|---|
NULL |
any | any | EINVAL |
tidak dimodifikasi |
any | any | NULL |
EINVAL |
strDest[0] atur ke 0 |
any | 0 | any | EINVAL |
tidak dimodifikasi |
tidak NULL |
terlalu kecil | any | ERANGE |
strDest[0] atur ke 0 |
Keterangan
Fungsi-fungsi ini mencoba menyalin karakter pertama D
ke strDest
strSource
, di mana D
lebih sedikit count
dan panjang .strSource
Jika karakter tersebut D
akan pas di dalam strDest
(yang ukurannya diberikan sebagai numberOfElements
) dan masih meninggalkan ruang untuk terminator null, maka karakter tersebut disalin dan null yang mengakhiri ditambahkan; jika tidak, strDest[0]
diatur ke karakter null dan handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter.
Ada pengecualian untuk paragraf di atas. Jika count
adalah _TRUNCATE
, maka sebanyak strSource
yang akan masuk ke dalam strDest
disalin sementara masih meninggalkan ruang untuk penghentian null, yang selalu ditambahkan.
Contohnya,
char dst[5];
strncpy_s(dst, 5, "a long string", 5);
berarti bahwa strncpy_s
menyalin lima karakter ke dalam buffer 5-byte. Salinan ini tidak akan meninggalkan ruang untuk terminator null, sehingga strncpy_s
nol keluar string, dan memanggil handler parameter yang tidak valid.
Jika perilaku pemotongan diperlukan, gunakan _TRUNCATE
atau (size
- 1):
strncpy_s(dst, 5, "a long string", _TRUNCATE);
strncpy_s(dst, 5, "a long string", 4);
Tidak seperti strncpy
, jika count
lebih besar dari panjang strSource
, string tujuan TIDAK diisi dengan karakter null hingga panjang count
.
Perilaku strncpy_s
tidak terdefinisi jika string sumber dan tujuan tumpang tindih.
Jika strDest
atau strSource
, NULL
atau numberOfElements
adalah 0, handler parameter yang tidak valid dipanggil. Jika eksekusi diizinkan untuk melanjutkan, fungsi mengembalikan EINVAL
dan mengatur errno
ke EINVAL
.
wcsncpy_s
dan _mbsncpy_s
adalah versi karakter lebar dan multibyte-character dari strncpy_s
. Argumen dan nilai pengembalian dan wcsncpy_s
mbsncpy_s
bervariasi sesuai. Keenam fungsi ini berulah secara identik jika tidak.
Nilai output dipengaruhi oleh pengaturan LC_CTYPE
pengaturan kategori lokal. Untuk informasi selengkapnya, lihat setlocale
. Versi fungsi-fungsi ini tanpa _l
akhiran menggunakan lokal saat ini untuk perilaku tergantung lokal ini; versi dengan _l
akhiran identik kecuali bahwa mereka menggunakan parameter lokal yang diteruskan sebagai gantinya. Untuk informasi selengkapnya, lihat Lokal.
Di C++, menggunakan fungsi-fungsi ini disederhanakan oleh kelebihan beban templat; kelebihan beban dapat menyimpulkan panjang buffer secara otomatis (menghilangkan kebutuhan untuk menentukan argumen ukuran) dan mereka dapat secara otomatis mengganti fungsi lama yang tidak aman dengan rekan-rekan yang lebih baru dan 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 fungsi teks generik
Fungsi dalam tchar.h
kolom memetakan ke fungsi di kolom lain tergantung pada kumpulan karakter yang ditentukan pada waktu kompilasi.
tchar.h Rutin |
_UNICODE dan _MBCS tidak ditentukan |
_MBCS Didefinisikan |
_UNICODE Didefinisikan |
---|---|---|---|
_tcsncpy_s |
strncpy_s |
_mbsnbcpy_s |
wcsncpy_s |
_tcsncpy_s_l |
_strncpy_s_l |
_mbsnbcpy_s_l |
_wcsncpy_s_l |
_tcsnccpy_s |
strncpy_s |
_mbsncpy_s |
_wcsncpy_s |
_tcsnccpy_s_l |
_strncpy_s_l |
_mbsncpy_s_l |
_wcsncpy_s_l |
Catatan
_strncpy_s_l
, _wcsncpy_s_l
dan _mbsncpy_s_l
tidak memiliki ketergantungan lokal. Mereka disediakan hanya untuk _tcsncpy_s_l
dan tidak dimaksudkan untuk dipanggil secara langsung.
Persyaratan
Rutin | Header yang diperlukan |
---|---|
strncpy_s , _strncpy_s_l |
<string.h> |
wcsncpy_s , _wcsncpy_s_l |
<string.h> atau <wchar.h> |
_mbsncpy_s , _mbsncpy_s_l |
<mbstring.h> |
Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.
Contoh: Menyalin karakter ke buffer
// crt_strncpy_s_1.cpp
// compile with: /MTd
// these #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h> // For _CrtSetReportMode
#include <errno.h>
// This example uses a 10-byte destination buffer.
errno_t strncpy_s_tester( const char * src,
int count )
{
char dest[10];
printf( "\n" );
if ( count == _TRUNCATE )
printf( "Copying '%s' to %d-byte buffer dest with truncation semantics\n",
src, _countof(dest) );
else
printf( "Copying %d chars of '%s' to %d-byte buffer dest\n",
count, src, _countof(dest) );
errno_t err = strncpy_s( dest, _countof(dest), src, count );
printf( " new contents of dest: '%s'\n", dest );
return err;
}
void Examples()
{
strncpy_s_tester( "howdy", 4 );
strncpy_s_tester( "howdy", 5 );
strncpy_s_tester( "howdy", 6 );
printf( "\nDestination buffer too small:\n" );
strncpy_s_tester( "Hi there!!", 10 );
printf( "\nTruncation examples:\n" );
errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
printf( " truncation %s occur\n", err == STRUNCATE ? "did"
: "did not" );
err = strncpy_s_tester( "Howdy.", _TRUNCATE );
printf( " truncation %s occur\n", err == STRUNCATE ? "did"
: "did not" );
printf( "\nSecure template overload example:\n" );
char dest[10];
strncpy( dest, "very very very long", 15 );
// With secure template overloads enabled (see #defines at
// top of file), the preceding line is replaced by
// strncpy_s( dest, _countof(dest), "very very very long", 15 );
// Instead of causing a buffer overrun, strncpy_s invokes
// the invalid parameter handler.
// If secure template overloads were disabled, strncpy would
// copy 15 characters and overrun the dest buffer.
printf( " new contents of dest: '%s'\n", dest );
}
void myInvalidParameterHandler(
const wchar_t* expression,
const wchar_t* function,
const wchar_t* file,
unsigned int line,
uintptr_t pReserved)
{
wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}
int main( void )
{
_invalid_parameter_handler oldHandler, newHandler;
newHandler = myInvalidParameterHandler;
oldHandler = _set_invalid_parameter_handler(newHandler);
// Disable the message box for assertions.
_CrtSetReportMode(_CRT_ASSERT, 0);
Examples();
}
Copying 4 chars of 'howdy' to 10-byte buffer dest
new contents of dest: 'howd'
Copying 5 chars of 'howdy' to 10-byte buffer dest
new contents of dest: 'howdy'
Copying 6 chars of 'howdy' to 10-byte buffer dest
new contents of dest: 'howdy'
Destination buffer too small:
Copying 10 chars of 'Hi there!!' to 10-byte buffer dest
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
new contents of dest: ''
Truncation examples:
Copying 'How do you do?' to 10-byte buffer dest with truncation semantics
new contents of dest: 'How do yo'
truncation did occur
Copying 'Howdy.' to 10-byte buffer dest with truncation semantics
new contents of dest: 'Howdy.'
truncation did not occur
Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
new contents of dest: ''
Contoh: strncpy
dan strncpy_s
// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s
#include <stdio.h>
#include <stdlib.h>
int main( void )
{
char a[20] = "test";
char s[20];
// simple strncpy usage:
strcpy_s( s, 20, "dogs like cats" );
printf( "Original string:\n '%s'\n", s );
// Here we can't use strncpy_s since we don't
// want null termination
strncpy( s, "mice", 4 );
printf( "After strncpy (no null-termination):\n '%s'\n", s );
strncpy( s+5, "love", 4 );
printf( "After strncpy into middle of string:\n '%s'\n", s );
// If we use strncpy_s, the string is terminated
strncpy_s( s, _countof(s), "mice", 4 );
printf( "After strncpy_s (with null-termination):\n '%s'\n", s );
}
Original string:
'dogs like cats'
After strncpy (no null-termination):
'mice like cats'
After strncpy into middle of string:
'mice love cats'
After strncpy_s (with null-termination):
'mice'
Lihat juga
Manipulasi string
Lokal
Interpretasi urutan karakter multibyte
_mbsnbcpy
, _mbsnbcpy_l
strcat_s
, , wcscat_s
_mbscat_s
strcmp
, , wcscmp
_mbscmp
strcpy_s
, , wcscpy_s
_mbscpy_s
strncat_s
, , _strncat_s_l
wcsncat_s
, _wcsncat_s_l
, , _mbsncat_s
,_mbsncat_s_l
strncmp
, , wcsncmp
_mbsncmp
,_mbsncmp_l
_strnicmp
, , _wcsnicmp
_mbsnicmp
, _strnicmp_l
, , _wcsnicmp_l
,_mbsnicmp_l
strrchr
, , wcsrchr
_mbsrchr
,_mbsrchr_l
_strset
, , _strset_l
_wcsset
, _wcsset_l
, , _mbsset
,_mbsset_l
strspn
, , wcsspn
_mbsspn
,_mbsspn_l
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk