wcstombs_s, _wcstombs_s_lwcstombs_s, _wcstombs_s_l

• 11/04/2016
• 6 minuti per la lettura
• Autori di contributi
  • 
  • 
  • 
  • 
  • 

Converte una sequenza di caratteri wide in una sequenza di caratteri multibyte corrispondente.Converts a sequence of wide characters to a corresponding sequence of multibyte characters. Questa è una versione di wcstombs, _wcstombs_l che include miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.A version of wcstombs, _wcstombs_l with security enhancements as described in Security Features in the CRT.

SintassiSyntax

errno_t wcstombs_s(  
   size_t *pReturnValue,  
   char *mbstr,  
   size_t sizeInBytes,  
   const wchar_t *wcstr,  
   size_t count   
);  

errno_t _wcstombs_s_l(  
   size_t *pReturnValue,  
   char *mbstr,  
   size_t sizeInBytes,  
   const wchar_t *wcstr,  
   size_t count,  
   _locale_t locale  
);  

template <size_t size>  
errno_t wcstombs_s(  
   size_t *pReturnValue,  
   char (&mbstr)[size],  
   const wchar_t *wcstr,  
   size_t count   
); // C++ only  

template <size_t size>  
errno_t _wcstombs_s_l(  
   size_t *pReturnValue,  
   char (&mbstr)[size],  
   const wchar_t *wcstr,  
   size_t count,  
   _locale_t locale  
); // C++ only  

ParametriParameters

[out] pReturnValue[out] pReturnValue
Numero di caratteri convertiti.The number of characters converted.

[out] mbstr[out] mbstr
Indirizzo di un buffer per la stringa di caratteri multibyte convertita risultante.The address of a buffer for the resulting converted multibyte character string.

[in] sizeInBytes[in] sizeInBytes
Le dimensioni in byte del mbstr buffer.The size in bytes of the mbstr buffer.

[in] wcstr[in] wcstr
Punta alla stringa di caratteri wide da convertire.Points to the wide character string to be converted.

[in] conteggio[in] count
Il numero massimo di byte da archiviare nel mbstr buffer, escluso il carattere di terminazione null o truncate.The maximum number of bytes to store in the mbstr buffer, not including the terminating null character, or _TRUNCATE.

[in] internazionali[in] locale
Impostazioni locali da usare.The locale to use.

Valore restituitoReturn Value

Zero in caso di esito positivo, un codice di errore in caso di esito negativo.Zero if successful, an error code on failure.

Se si verifica una di queste condizioni, viene richiamata l'eccezione di parametro non valido come descritto in Convalida dei parametri.If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . Se l'esecuzione può continuare, la funzione restituisce un codice errore e imposta errno come indicato nella tabella.If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

NoteRemarks

Il wcstombs_s funzione converte una stringa di caratteri wide a cui puntata wcstr in caratteri multibyte memorizzati nel buffer a cui puntato mbstr.The wcstombs_s function converts a string of wide characters pointed to by wcstr into multibyte characters stored in the buffer pointed to by mbstr. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:The conversion will continue for each character until one of these conditions is met:

• Viene rilevato un carattere Null wideA null wide character is encountered

• Viene rilevato un carattere wide che non può essere convertitoA wide character that cannot be converted is encountered

• Il numero di byte archiviato nel mbstr buffer equals conteggio.The number of bytes stored in the mbstr buffer equals count.

La stringa di destinazione termina sempre con Null, anche in caso di errore.The destination string is always null-terminated (even in the case of an error).

Se conteggio è il valore speciale truncate, quindi wcstombs_s Converte la porzione della stringa come verrà adattata il buffer di destinazione, lasciando spazio per una terminazione null.If count is the special value _TRUNCATE, then wcstombs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. Se la stringa verrà troncata, il valore restituito è STRUNCATE, e la conversione viene considerata riuscita.If the string is truncated, the return value is STRUNCATE, and the conversion is considered successful.

Se wcstombs_s converte correttamente la stringa di origine, inserisce la dimensione in byte della stringa convertita, incluso il terminatore null, in *pReturnValue (fornito pReturnValue non NULL).If wcstombs_s successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). Questo errore si verifica anche se il mbstr argomento NULL e fornisce un modo per determinare le dimensioni del buffer richiesto.This occurs even if the mbstr argument is NULL and provides a way to determine the required buffer size. Si noti che se mbstr è NULL, conteggio viene ignorato.Note that if mbstr is NULL, count is ignored.

Se wcstombs_s rileva un carattere wide che non può convertire in carattere multibyte, inserisce 0 in *pReturnValue, imposta il buffer di destinazione su una stringa vuota, imposta errno su EILSEQ e restituisce EILSEQ.If wcstombs_s encounters a wide character it cannot convert to a multibyte character, it puts 0 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

Se le sequenze a cui puntava wcstr e mbstr si sovrappongono, il comportamento di wcstombs_s non è definito.If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs_s is undefined.

wcstombs_s usa le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali. La funzione _wcstombs_s_l è identica a wcstombs, ma usa le impostazioni locali passate.wcstombs_s uses the current locale for any locale-dependent behavior; _wcstombs_s_l is identical to wcstombs except that it uses the locale passed in instead. Per altre informazioni, vedere Locale.For more information, see Locale.

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

RequisitiRequirements

Per altre informazioni sulla compatibilità, vedere Compatibilità.For additional compatibility information, see Compatibility.

EsempioExample

Questo programma illustra il comportamento della funzione wcstombs_s.This program illustrates the behavior of the wcstombs_s function.

// crt_wcstombs_s.c  
// This example converts a wide character  
// string to a multibyte character string.  
#include <stdio.h>  
#include <stdlib.h>  
#include <assert.h>  

#define BUFFER_SIZE 100  

int main( void )  
{  
    size_t   i;  
    char      *pMBBuffer = (char *)malloc( BUFFER_SIZE );  
    wchar_t*pWCBuffer = L"Hello, world.";  

    printf( "Convert wide-character string:\n" );  

    // Conversion  
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,   
               pWCBuffer, (size_t)BUFFER_SIZE );  

    // Output  
    printf("   Characters converted: %u\n", i);  
    printf("    Multibyte character: %s\n\n",  
     pMBBuffer );  

    // Free multibyte character buffer  
    if (pMBBuffer)  
    {  
    free(pMBBuffer);  
    }  
}  

Convert wide-character string:  
   Characters converted: 14  
    Multibyte character: Hello, world.  

Vedere ancheSee Also

Data Conversion (Conversione dei dati)Data Conversion
Locale (Impostazioni locali)Locale
_mbclen, mblen, _mblen_l _mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l wctomb_s, _wctomb_s_l
WideCharToMultiByteWideCharToMultiByte