wcstombs_s, _wcstombs_s_l

Artikel
02/26/2013

Konvertiert eine Sequenz von Breitzeichen in eine entsprechende Sequenz von Mehrbytezeichen.Eine Version von wcstombs, _wcstombs_l mit unter Security Enhancements, wie in Sicherheitsfeatures im CRTbeschrieben.

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

Parameter

[out] pReturnValue
Die Anzahl von Zeichen konvertiert.
[out] mbstr
Die Adresse eines Puffers für die resultierende konvertierte Mehrbytezeichen zeichenkette.
[in]sizeInBytes
Die Größe in Byte) des Puffers mbstr .
[in] wcstr
Punkte zu konvertierende Zeichenfolge mit Breitzeichen.
[in] count
Die maximale Anzahl der im Puffer mbstr , nicht von den einschließlich des abschließenden NULL-Zeichens gespeichert werden soll, oder _TRUNCATEBreitzeichen.
[in] locale
Das zu verwendende Gebietsschema.

Rückgabewert

Beliebige wenn erfolgreich, ein Fehlercode auf Fehler.

Fehlerzustand	Rückgabewert und errno
mbstr ist NULL und sizeInBytes > 0	EINVAL
wcstr ist NULL	EINVAL
Der Zielpuffer ist zu klein, die das konvertierte Zeichenfolge aufzunehmen (es sei denn, count_TRUNCATEist. siehe Hinweise)	ERANGE

Wenn eine dieser Bedingungen auftritt, wird die ungültige Parameter ausnahme aufgerufen, wie in Parametervalidierung beschrieben.Wenn die Ausführung ermöglicht wird, um fortzufahren, gibt die Funktion einen Fehlercode zurück und legt ihn fest errno , wie in der Tabelle angegeben.

Hinweise

Die wcstombs_s-Funktion konvertiert eine Zeichenfolge mit Breitzeichen, die durch wcstr in die Mehrbytezeichen dargestellt werden, die im Puffer gespeichert werden, der durch mbstrdargestellt wird.Die Konvertierung wird für jedes Zeichen fort, bis eine dieser Bedingungen erfüllt ist:

Ein NULL Breitzeichen auftritt
Ein Breitzeichen, das nicht konvertiert werden kann, wird gefunden
Die Anzahl der Bytes, die in mbstr Puffer gespeichert werden, entspricht count.

Die Zielzeichenfolge ist immer auf NULL endende (selbst im Falle eines Fehlers).

Wenn count um den besonderen Wert _TRUNCATEist, konvertiert wcstombs_s so viel der Zeichenfolge in den Zielpuffer passt, während noch Platz für ein NULL-Abschlusszeichen.

Wenn die Quellzeichenfolge wcstombs_s erfolgreich konvertiert, wird die Größe in Bytes der konvertierten Zeichenfolge, einschließlich des NULL-Terminators, in *pReturnValue (bereitgestelltes pReturnValue ist nicht NULL).Dies tritt auf, mbstr , selbst wenn das Argument NULL und ermöglicht die erforderliche Puffergröße zu ermitteln.Beachten Sie, dass beim mbstrNULList, count ignoriert wird.

Wenn ein Breitzeichen trifft, wcstombs_s nicht auf einen Mehrbytezeichen konvertieren kann, wird 0 an *einpReturnValuelegt den Zielpuffer zu einer leeren Zeichenfolge errno legt diesen fest EILSEQfest und gibt an EILSEQzurück.

Wenn die Sequenzen, die über wcstr und mbstr Überlappung, das Verhalten von wcstombs_s dargestellt werden, nicht definiert ist.

Sicherheitshinweis
Stellen Sie sicher, dass wcstr und mbstr sich nicht überschneiden und dass count ordnungsgemäß die Anzahl der Breitzeichen, die auf Convert widerspiegelt.

wcstombs_s verwendet das aktuelle Gebietsschema für ein beliebiges gebietsschemaabhängige Verhalten. _wcstombs_s_l ist mit wcstombs identisch, mit der Ausnahme, dass sie verwendet das Gebietsschema, das Stattdessen übergeben wird.Weitere Informationen finden Sie unter Gebietsschema.

In C++ unter Verwendung dieser Funktionen wird von Vorlagen Operatoren vereinfacht. Die Überladungen können die Pufferlänge (die Anforderung automatisch beseitigend ableiten, die ein Argument angegeben) und können nicht-sicheren, die älteren Funktionen über ihre Äquivalente sicheren, aktuelleren automatisch ersetzen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Anforderungen

Routine	Erforderlicher Header
wcstombs_s	<stdlib.h>

Um Kompatibilität zusätzlichen Informationen finden Sie unter Kompatibilität in der Einführung.

Beispiel

Dieses Programm wird das Verhalten der wcstombs_s-Funktion.

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