Condividi tramite

strcpy_s, wcscpy_s, _mbscpy_s_mbscpy_s_l

  • Articolo

Copia una stringa. Queste versioni di , includono _mbscpy miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT. wcscpystrcpy

Importante

_mbscpy_s e _mbscpy_s_l non possono essere usati nelle applicazioni eseguite in Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).

Sintassi

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

Parametri

dest
Posizione del buffer di stringa di destinazione.

dest_size
Dimensione del buffer della stringa di destinazione nelle unità char per funzioni narrow e multibyte e nelle unità wchar_t per funzioni "wide". Questo valore deve essere maggiore di zero e non maggiore di RSIZE_MAX. Assicurarsi che queste dimensioni siano responsabili della terminazione NULL dopo la stringa.

src
Buffer della stringa di origine che termina con Null.

locale
Impostazioni locali da usare.

Valore restituito

Zero in caso di esito positivo; in caso contrario un errore.

Condizioni di errore

dest dest_size src Valore restituito Contenuto di dest
NULL qualsiasi qualsiasi EINVAL non modificato
qualsiasi qualsiasi NULL EINVAL dest[0] impostato su 0
qualsiasi 0 o troppo piccolo qualsiasi ERANGE dest[0] impostato su 0

Osservazioni:

La funzione strcpy_s copia il contenuto nell'indirizzo di src, incluso il carattere null di terminazione, nel percorso specificato da dest. La stringa di destinazione deve essere sufficientemente grande da contenere la stringa di origine e il relativo carattere Null di terminazione. Se le stringhe di origine e di destinazione si sovrappongono, il comportamento di strcpy_s non è definito.

wcscpy_s è la versione a caratteri wide di strcpy_s e _mbscpy_s è la versione a caratteri multibyte. Gli argomenti di sono stringhe di wcscpy_s caratteri wide. Gli argomenti di _mbscpy_s e _mbscpy_s_l sono stringhe di caratteri multibyte. A parte ciò, queste funzioni si comportano in modo identico. _mbscpy_s_l è identico a _mbscpy_s , ad eccezione del fatto che usa il parametro delle impostazioni locali passato anziché le impostazioni locali correnti. Per ulteriori informazioni, vedere locale.

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

Quando l'esecuzione dell'operazione si conclude correttamente, la stringa di destinazione è sempre con terminazione Null.

In C++, l'uso di queste funzioni è semplificato dagli overload del modello che possono dedurre automaticamente la lunghezza del buffer, in modo che non sia necessario specificare un argomento dimensione. E possono sostituire automaticamente funzioni meno recenti e meno sicure con controparti più recenti e sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Le versioni della libreria di debug di queste funzioni riempiono prima di tutto il buffer con 0xFE. Per disabilitare questo comportamento, usare _CrtSetDebugFillThreshold.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

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

Requisiti

Ciclo Intestazione obbligatoria
strcpy_s <string.h>
wcscpy_s <string.h> oppure <wchar.h>
_mbscpy_s <mbstring.h>

Queste funzioni sono specifiche di Microsoft. Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

A differenza del codice di qualità di produzione, questo esempio chiama le funzioni stringa sicure senza verificare la presenza di errori:

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

Quando si compila codice C++, le versioni del modello possono essere più facili da usare.

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

Vedi anche

Manipolazione delle stringhe
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