wcstombs, _wcstombs_l

Artikel
02/26/2013

Konvertiert eine Sequenz von Breitzeichen in eine entsprechende Sequenz von Mehrbytezeichen.Sicherere Versionen dieser Funktionen sind verfügbar. Weitere Informationen finden Sie unter wcstombs_s, _wcstombs_s_l.

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

mbstr
Die Adresse einer Sequenz von Mehrbytezeichen.
wcstr
Die Adresse einer Sequenz von Breitzeichen.
count
Die maximale Anzahl von Bytes, die in der Mehrbyten Ausgabezeichenfolge gespeichert werden können.
locale
Das zu verwendende Gebietsschema.

Rückgabewert

Wenn wcstombs die erfolgreich Mehrbyte Zeichenfolge konvertiert, gibt sie die Anzahl von Bytes zurück, die in die Mehrbyte Ausgabezeichenfolge ohne endenden NULL geschrieben werden (sofern vorhanden).Wenn das Argument mbstrNULList, gibt wcstombs die erforderliche Größe in Bytes der Zielzeichenfolge zurück.Wenn ein Breitzeichen trifft, wcstombs nicht auf einen Mehrbytezeichen konvertieren kann, gibt es 1 umgewandelt, um size_t einzugeben EILSEQzu errno zurück und legt ihn fest.

Hinweise

Die wcstombs-Funktion konvertiert die Zeichenfolge mit Breitzeichen, die durch den entsprechenden wcstr Mehrbytezeichen gezeigten und speichert die Ergebnisse in mbstr Array.Der count-Parameter gibt die maximale Anzahl von Bytes an, die in der Mehrbyten Ausgabezeichenfolge (d. h. die Größe von mbstr) gespeichert werden können.Im Allgemeinen ist dies nicht, wie viele Bytes erforderlich sind, wenn sie eine Zeichenfolge mit Breitzeichen konvertieren.Einige Breitzeichen benötigen lediglich ein Byte in der Ausgabezeichenfolge. Zwei weitere erfordern.Wenn zwei Bytes an der Mehrbyten Ausgabezeichenfolge für die einzelnen Breitzeichen, die in der Eingabezeichenfolge NULLBreitzeichen (einschließlich) vorhanden ist, wird das Ergebnis garantiert angepasst.

Wenn das wcstombs NULL-Breitzeichen (L \ 0 ') entweder vor oder auftritt, wenn count auftritt, es zu einem 8-Bit 0 konvertiert und beendet wird.Daher ist die Mehrbytezeichen zeichenkette unter mbstr auf NULL endende nur, wenn ein wcstombs NULL-Breitzeichen bei der Konvertierung findet.Wenn die Sequenzen, die über wcstr und mbstr Überlappung, das Verhalten von wcstombs dargestellt werden, nicht definiert ist.

Wenn das Argument mbstrNULList, gibt wcstombs die erforderliche Größe in Bytes der Zielzeichenfolge zurück.

wcstombs überprüft seine Parameter.Wenn wcstrNULList oder wenn count größer alsINT_MAXist, Aufrufe dieser Funktion der ungültige Parameter für, wie in Parametervalidierung beschrieben.Wenn die Ausführung zulässig ist, um fortzufahren, legt die Funktion errno zu EINVAL fest und gibt -1 zurück.

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

In C++ haben Überladungen Vorlagen, die diese Funktionen aufrufen, um das neueres, Entsprechungen dieser Funktionen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Anforderungen

Routine	Erforderlicher Header
wcstombs	<stdlib.h>
_wcstombs_l	<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-Funktion.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}