wcstombs_s, _wcstombs_s_lwcstombs_s, _wcstombs_s_l
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.
Condizione di erroreError condition | Valore restituito e errno Return value and errno |
---|---|
mbstr è NULL e sizeInBytes > 0mbstr is NULL and sizeInBytes > 0 |
EINVAL |
wcstr è NULL wcstr is NULL |
EINVAL |
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che non conteggio è _TRUNCATE ; vedere la sezione Osservazioni di seguito)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE ; see Remarks below) |
ERANGE |
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.
Importante
Verificare che wcstr e mbstr si sovrappongano e che conteggio rispecchi correttamente il numero di caratteri wide da convertire.Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of wide characters to convert.
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
RoutineRoutine | Intestazione obbligatoriaRequired header |
---|---|
wcstombs_s |
<stdlib.h><stdlib.h> |
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