strcpy_s, wcscpy_s, _mbscpy_s

Articolo
06/09/2015

Copia una stringa. Queste versioni di strcpy, wcscpy, _mbscpy contengono i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

Importante

_mbscpy_s non può essere utilizzato nelle applicazioni eseguite in Windows Runtime.Per ulteriori informazioni, vedere Funzioni CRT non supportate con /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

Parametri

strDestination
Posizione del buffer della stringa di destinazione.
numberOfElements
Dimensione del buffer della stringa di destinazione.
strSource
Buffer della stringa di origine che termina con Null.

Valore restituito

Zero è un esito positivo. In caso contrario, un errore.

Condizioni di errore

strDestination	numberOfElements	strSource	Valore restituito	Contenuto di strDestination.
NULL	any	any	EINVAL	non modificato
any	any	NULL	EINVAL	strDestination[0] impostato su 0
any	0 o troppo piccolo	any	ERANGE	strDestination[0] impostato su 0

Note

La funzione strcpy_s copia il contenuto nell'indirizzo di strSource, incluso il carattere di terminazione null, nella posizione specificata da strDestination. La stringa di destinazione deve essere sufficientemente grande da contenere la stringa di origine e il carattere di terminazione null. Il comportamento di strcpy_s non è definito se le stringhe di origine e di destinazione si sovrappongono.

wcscpy_s è la versione con caratteri wide di strcpy_s e _mbscpy_s è la versione a caratteri multibyte. Gli argomenti e il valore restituito di wcscpy_s sono stringhe di caratteri di tipo "wide", quelli di _mbscpy_s sono stringhe di caratteri multibyte. Altrimenti queste tre funzioni si comportano in modo identico.

Se strDestination o strSource è un puntatore null, o se la stringa di destinazione è troppo piccola, viene richiamato il gestore dei parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni restituiscono EINVAL e impostano errno su EINVAL quando strDestination o strSource è un puntatore null e restituiscono ERANGE e impostano errno su ERANGE quando la stringa di destinazione è troppo piccola.

Quando l'esecuzione è corretta, la stringa di destinazione è sempre con terminazione null.

In C++, l'utilizzo di queste funzioni è semplificato dagli overload dei modelli che possono dedurre la lunghezza del buffer automaticamente in modo che non sia necessario specificare un argomento di dimensione e possono sostituire automaticamente le funzioni precedenti e meno sicure con le controparti più recenti e sicure. Per ulteriori informazioni, vedere Overload di modelli sicuri.

La versione di debug di queste funzioni per prima cosa riempiono il buffer con il valore 0xFE. Per disattivare questo comportamento, utilizzare _CrtSetDebugFillThreshold.

Mapping di routine su testo generico

Routine TCHAR.H	_UNICODE e _MBCS non definiti	_MBCS definito	_UNICODE definito
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Requisiti

Routine	Intestazione obbligatoria
strcpy_s	<string.h>
wcscpy_s	<string.h> o <wchar.h>
_mbscpy_s	<mbstring.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità.

Esempio

// 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 );
}