wcstombs, _wcstombs_l

Artikel
06/09/2015

Konvertiert eine Sequenz von Breitzeichen in der entsprechenden Reihenfolge von Mehrbytezeichen. Sicherere Versionen dieser Funktionen sind verfügbar. Informationen dazu 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 der Mehrbytezeichen.
wcstr
Die Adresse einer Sequenz der Breitzeichen.
count
Die maximale Anzahl von Bytes, die in der Mehrbyteausgabezeichenfolge gespeichert werden können.
locale
Das zu verwendende Gebietsschema.

Rückgabewert

Wenn wcstombs erfolgreich die Mehrbytezeichenfolge konvertiert, wird die Anzahl von Bytes zurück, die in die Mehrbyteausgabezeichenfolge, ausschließlich endendes NULL geschrieben werden (falls vorhanden). Wenn das Argument mbstrNULL ist, gibt wcstombs die erforderlichen Größe in Bytes der Zielzeichenfolge zurück. Wenn wcstombs ein Breitzeichen trifft, das er nicht auf einen Mehrbytezeichen konvertieren kann, können Sie - 1 umgewandelt, um zu size_t zurück und legt errno auf EILSEQ fest.

Hinweise

Die wcstombs-Funktion konvertiert die Zeichenfolge mit Breitzeichen, die von wcstr in den entsprechenden Mehrbytezeichen gezeigt wird und speichert die Ergebnisse im mbstr - Array. Der count-Parameter gibt die maximale Anzahl der Bytes an, die in der Mehrbyteausgabezeichenfolge (das heißt, die Größe von mbstr) gespeichert werden können. Im Allgemeinen wird jedoch nicht, wie viele Bytes erforderlich sind, wenn Sie eine Zeichenfolge mit Breitzeichen konvertieren. Einige Breitzeichen benötigen lediglich ein Byte in der Ausgabezeichenfolge; andere benötigen zwei. Wenn zwei Bytes in der Mehrbyteausgabezeichenfolge für die einzelnen Breitzeichen in der Eingabezeichenfolge (Breitzeichen) einschließlich NULL gibt, ist das Ergebnis garantiert, um anzupassen.

Wenn wcstombs das NULL-Breitzeichen (L"\0") entweder vor trifft oder, wenn count auftritt, wird es zu einem äußerst 0 konvertiert und anhält. Daher ist die Mehrbytezeichenzeichenfolge bei mbstr auf NULL endende nur, wenn wcstombs ein NULL-Breitzeichen während der Konvertierung gefunden wird. Wenn die Sequenzen, die von wcstr und mbstr Überlappung, das Verhalten von wcstombs dargestellt werden, die definiert.

Wenn das Argument mbstrNULL ist, gibt wcstombs die erforderlichen Größe in Bytes der Zielzeichenfolge zurück.

wcstombs überprüft die eigenen Parameter. Wenn wcstrNULL ist oder wenn count größer als INT_MAX ist, Aufrufe dieser Funktion Parameterhandler der ungültige, wie in Parametervalidierung beschrieben. Wenn die Ausführung zulässig ist, um fortzufahren, legt die Funktion errno auf EINVAL fest und gibt -1 zurück.

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

In C++ haben diese Funktionen Vorlagenüberladungen, mit denen die neueren, sicheren Entsprechungen dieser Funktionen aufgerufen werden. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Anforderungen

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

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