wcstombs_s, _wcstombs_s_l

Konvertiert eine Breitzeichensequenz in eine entsprechende Multibyte-Zeichensequenz. Eine Version von wcstombs, _wcstombs_l mit Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Syntax

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

pReturnValue
Die Größe in Byte der konvertierten Zeichenfolge, einschließlich des Null-Terminators.

mbstr
Die Pufferadresse für die resultierende konvertierte Multibyte-Zeichenfolge.

sizeInBytes
Die Größe mbstr-Puffers in Bytes.

wcstr
Zeigt auf die zu konvertierende Breitzeichenfolge.

count
Die maximale Anzahl von Bytes, die mbstr im Puffer gespeichert werden sollen, nicht einschließlich des endenden NULL-Zeichens oder _TRUNCATE.

locale
Das zu verwendende Gebietsschema.

Rückgabewert

Null, wenn erfolgreich, Fehlercode bei Fehler.

Wenn eine dieser Bedingungen auftritt, wird die ausnahme für ungültige Parameter aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die Ausführung fortgesetzt werden kann, gibt die Funktion einen Fehlercode zurück und legt errno wie in der Tabelle angegeben fest.

Hinweise

Die wcstombs_s-Funktion konvertiert eine Zeichenfolge mit Breitzeichen, auf die von wcstr gezeigt wird, in im Puffer gespeicherte Multibytezeichen, auf die von mbstr gezeigt wird. Die Konvertierung wird für jedes Zeichen fortgesetzt, bis eine der folgenden Bedingungen eintritt:

• Ein Breitzeichen NULL wird erkannt.

• Es wird ein breites Zeichen gefunden, das nicht konvertiert werden kann.

• Die Anzahl der Bytes, die im mbstr-Puffer gespeichert sind, ist gleich count.

Die Zielzeichenfolge wird immer null beendet (auch wenn ein Fehler auftritt).

Wenn count es sich um den speziellen Wert _TRUNCATEhandelt, wcstombs_s wird so viel der Zeichenfolge konvertiert, wie er in den Zielpuffer passt, während der Raum für einen Null-Endator noch nicht verfügbar ist. Wenn die Zeichenfolge abgeschnitten wird, lautet STRUNCATEder Rückgabewert , und die Konvertierung wird als erfolgreich betrachtet.

Wenn wcstombs_s die Quellzeichenfolge erfolgreich konvertiert wird, fügt sie die Größe der konvertierten Zeichenfolge, einschließlich des Null-Terminators, in *pReturnValue (angegeben pReturnValue ist nicht NULL) ein. Die Größe wird auch dann berechnet, wenn das mbstr Argument lautet NULL. Sie bietet eine Möglichkeit, die erforderliche Puffergröße zu ermitteln. Ist mbstr dies NULLder Fehler , count wird ignoriert.

Wenn wcstombs_s ein breites Zeichen auftritt, das nicht in ein Multibyte-Zeichen konvertiert werden kann, wird 0 in *ReturnValueden Zielpuffer gesetzt, auf eine leere Zeichenfolge festgelegt, festgelegt errno EILSEQund zurückgegeben EILSEQ.

Wenn die Sequenzen, auf die von wcstr und mbstr verwiesen wird, überlappen, ist das Verhalten von wcstombs_s nicht definiert.

wcstombs_s verwendet das aktuelle Gebietsschema für jedes Verhalten, das vom Gebietsschema abhängig ist; _wcstombs_s_l ist mit wcstombs identisch, nur dass sie stattdessen das übergebene Gebietsschema verwendet. 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 Secure Template Overloads.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Anforderungen

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

Dieses Programm stellt das Verhalten der Funktion wcstombs_s dar.

// 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 );
    const 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 - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

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

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

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

Siehe auch

Datenkonvertierung
Gebietsschema
_mbclen, mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte