wcstombs_s, _wcstombs_s_l

Artikel
06/09/2015

Konvertiert eine Sequenz von Breitzeichen in der entsprechenden Reihenfolge von Mehrbytezeichen. Eine Version von wcstombs, _wcstombs_l mit werden, wie in Sicherheitsfunktionen in der CRT beschrieben.

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 der Zeichen konvertiert.
[out] mbstr
Die Adresse eines Puffers für Zurückhalten konvertierte Mehrbytezeichenzeichenfolge.
[in]sizeInBytes
Die Größe in Bytes des Puffers mbstr.
[in] wcstr
Punkte die zu konvertierende Zeichenfolge mit Breitzeichen.
[in] count
Die maximale Anzahl im mbstr Puffer, nicht durch einschließlich des abschließenden NULL-Zeichens zu speichernden Breitzeichen, oder _TRUNCATE.
[in] locale
Das zu verwendende Gebietsschema.

Rückgabewert

Null, wenn erfolgreich, Fehlercode bei Fehler.

Fehlerstatus	Rückgabewert und errno
mbstr ist NULL und sizeInBytes > 0	EINVAL
wcstr ist NULL	EINVAL
Der Zielpuffer ist zu klein, die konvertierte Zeichenfolge zu enthalten (es sei denn, count ; _TRUNCATE ist siehe Hinweise) unten	ERANGE

Wenn diese Bedingungen auftritt, wird die ungültige Parameterausnahme aufgerufen, wie in Parametervalidierung beschrieben. Wenn die Ausführung zulässig ist, um fortzufahren, gibt die Funktion einen Fehlercode zurück und legt errno fest, wie in der Tabelle angegeben.

Hinweise

Die wcstombs_s-Funktion konvertiert eine Zeichenfolge mit Breitzeichen, die von wcstr in die Mehrbytezeichen dargestellt werden, die im Puffer gespeichert werden, auf den durch mbstr gezeigt wird. Die Konvertierung wird für jedes Zeichen fortgesetzt, bis eine dieser Bedingungen erfüllt ist:

Ein NULL-Makro Breitzeichen auftritt
Bei einem Breitzeichen, die nicht konvertiert werden kann, wird ausgeführt
Die Anzahl der Bytes, die im mbstr Puffer gespeichert werden, entspricht count.

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

Wenn count den speziellen Wert _TRUNCATE ist, konvertiert wcstombs_s so weit der Zeichenfolge, wie in den Zielpuffer passt, wobei Platz für einen Nullterminator weiterhin beibehalten.

Wenn wcstombs_s erfolgreich die Quellzeichenfolge konvertiert, wird die Größe in Bytes der konvertierten Zeichenfolge, einschließlich das NULL-Zeichen, in *(ein pReturnValue bereit gestelltes pReturnValue nicht NULL ist). Dies tritt auf, mbstr, wenn das Argument NULL und bietet eine Möglichkeit, die erforderliche Puffergröße zu ermitteln. Beachten Sie, dass, wenn mbstrNULL ist, die count ignoriert wird.

Wenn wcstombs_s ein Breitzeichen trifft, das er nicht auf einen Mehrbytezeichen konvertieren kann, wird 0 in *pReturnValue, legt den Zielpuffer auf eine leere Zeichenfolge fest, wird errno auf EILSEQ festgelegt und EILSEQ zurückgegeben.

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

Sicherheitshinweis
Stellen Sie sicher, dass wcstr und mbstr nicht überschneiden und dass count richtig die Anzahl der Breitzeichen an verschiedenen mitgeteilt.

wcstombs_s verwendet das aktuelle Gebietsschema jedes gebietsschemaabhängigen Verhalten; _wcstombs_s_l ist mit wcstombs identisch, es verwendet das Gebietsschema, das ein- stattdessen übergeben wird. Weitere Informationen finden Sie unter Locale.

In C++ wird die Verwendung dieser Funktionen durch Vorlagenüberladungen vereinfacht; die Überladungen können automatisch Rückschlüsse auf die Pufferlänge ziehen (wodurch kein Größenargument mehr angegeben werden muss), und sie können automatisch die älteren, nicht sicheren Funktionen durch ihre neueren, sicheren Entsprechungen ersetzen. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Anforderungen

Routine	Erforderlicher Header
wcstombs_s	<stdlib.h>

Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität in der Einführung.

Beispiel

Dieses Programm veranschaulicht das Verhalten der Funktion wcstombs_s.

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