`wcsrtombs_s`

Artikel
08/03/2024

Konvertieren von Breitzeichen in die Multibyte-Zeichenfolgendarstellung. Eine Version mit wcsrtombs Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Syntax

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // 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, oder _TRUNCATE.

mbstate
Ein Zeiger auf ein mbstate_t-Konvertierungszustandsobjekt.

Rückgabewert

Null, wenn erfolgreich, Fehlercode bei Fehler.

Fehlerbedingung	Rückgabewert und `errno`
`mbstr` ist `NULL` und `sizeInBytes`> 0	`EINVAL`
`wcstr` ist `NULL`.	`EINVAL`
Der Zielpuffer ist für die konvertierte Zeichenfolge zu klein (es sei denn, `count` ist gleich `_TRUNCATE`; siehe Abschnitt „Hinweise“)	`ERANGE`

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 wcsrtombs_s-Funktion konvertiert eine Zeichenfolge mit Breitzeichen, auf die indirekt von wcstr gezeigt wird, in im Puffer gespeicherte Multibytezeichen, auf die von mbstr gezeigt wird, und verwendet dafür den in mbstate enthaltenen Konvertierungsstatus. 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, wcsrtombs_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 wcsrtombs_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 wcsrtombs_s ein breites Zeichen auftritt, kann es nicht in ein Multibyte-Zeichen konvertiert werden, legt es -1 in *pReturnValue, legt den Zielpuffer auf eine leere Zeichenfolge fest, legt errno sie auf EILSEQund gibt zurück EILSEQ.

Wenn die Sequenzen, auf die von wcstr und mbstr verwiesen wird, überlappen, ist das Verhalten von wcsrtombs_s nicht definiert. wcsrtombs_s wird von der LC_TYPE-Kategorie des aktuellen Gebietsschemas beeinflusst.

Wichtig

Stellen Sie sicher, dass wcstr und mbstr nicht überlappen und dass count die Anzahl zu konvertierender Breitzeichen korrekt darstellt.

Die wcsrtombs_s Funktion unterscheidet sich von wcstombs_sder _wcstombs_s_l Neustartbarkeit. Der Konvertierungszustand wird für nachfolgende Aufrufe der gleichen oder anderer Funktionen, die neu gestartet werden können, in mbstate gespeichert. Wenn sowohl Funktionen, die neu gestartet werden können, als auch Funktionen, die nicht neu gestartet werden könnnen, verwendet werden, sind die Ergebnisse undefiniert. Beispiel: Eine Anwendung würde wcsrlen anstelle von wcslen verwenden, wenn ein nachfolgender Aufruf von wcsrtombs_s anstelle von wcstombs_s verwendet würde.

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.

Ausnahmen

Die wcsrtombs_s-Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufruft, während diese Funktion ausgeführt wird und mbstate NULL ist.

Beispiel

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Anforderungen

Routine	Erforderlicher Header
`wcsrtombs_s`	<wchar.h>

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Freigeben über