wcstombs_s, _wcstombs_s_l

Artykuł
06/09/2015

Konwertuje sekwencja znaków szerokości odpowiedniej sekwencji znaków wielobajtowych.Wersja z wcstombs, _wcstombs_l z rozszerzeń zabezpieczeń opisane w Funkcje zabezpieczeń w CRT.

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

Parametry

[out]pReturnValue
Liczba znaków konwertowane.
[out]mbstr
Adres buforu dla wynikowy ciąg znaków wielobajtowych przekonwertowane.
[w]sizeInBytes
Rozmiar w bajtach mbstr buforu.
[w]wcstr
Punkty do konwertowanego łańcucha szerokich znaków.
[w]count
Maksymalna liczba znaków szerokości mają być przechowywane w mbstr buforu, nie włączając kończącego znaku null lub _TRUNCATE.
[w]locale
Ustawienia regionalne, aby użyć.

Wartość zwracana

Zero, jeśli kończy się pomyślnie, kod błędu w przypadku awarii.

Warunek błędu	Zwraca wartość ierrno
mbstris NULL and sizeInBytes > 0	EINVAL
wcstrjestNULL	EINVAL
Bufor docelowy jest zbyt mały, aby pomieścił przekonwertowanym łańcuchem (chyba że count jest _TRUNCATE; Zobacz uwagi poniżej)	ERANGE

Jeśli występuje którykolwiek z tych warunków, wyjątek nieprawidłowy parametr jest wywoływany, jak opisano w Sprawdzanie poprawności parametru .Jeśli wykonanie może w dalszym ciągu, funkcja zwraca kod błędu i ustawia errno jak wskazano w tabeli.

Uwagi

wcstombs_s Funkcja konwertuje ciąg znaków szerokości wskazywanej przez wcstr do znaków wielobajtowych, przechowywane w buforze wskazywanej przez mbstr.Konwersja będzie kontynuowane dla każdego znaku, dopóki jeden z tych warunków jest spełniony:

Po napotkaniu null szerokich znaków
Po napotkaniu szerokiego znaku, który nie może zostać przekonwertowany
Liczba bajtów, przechowywane w mbstr buforu równa się count.

Ciąg docelowego jest zawsze zakończony zerem (nawet w przypadku wystąpienia błędu).

Jeśli count jest specjalna wartość _TRUNCATE, następnie wcstombs_s konwertuje tyle ciąg będą mieści się w bufor docelowy, pozostawiając nadal miejsca na null terminator.

Jeśli wcstombs_s pomyślnie konwertuje ciąg źródłowy umieszcza rozmiar w bajtach przekonwertowanym łańcuchem, łącznie z null terminator do *pReturnValue (pod warunkiem pReturnValue nie jest NULL).Dzieje się tak nawet wtedy, gdy mbstr argument jest NULL i daje możliwość określenia wymagany rozmiar buforu.Note that if mbstr is NULL, count is ignored.

Jeśli wcstombs_s napotka szerokiego znaku nie może przekonwertować znaków wielobajtowych, umieszcza 0 w *pReturnValue, ustawia bufor docelowy ciąg pusty, ustawia errno do EILSEQi zwraca EILSEQ.

Jeśli sekwencji wskazywanej przez wcstr i mbstr nachodzą na siebie, zachowanie wcstombs_s jest niezdefiniowane.

Uwaga dotycząca zabezpieczeń
Zapewnić, że wcstr i mbstr nie nakładają się i że count poprawnie odzwierciedla numer szerokości znaków do konwertowania.

wcstombs_swykorzystuje bieżące ustawienia regionalne dla wszelkich zachowanie zależnego od ustawień regionalnych; _wcstombs_s_ljest taka sama, jak wcstombs z wyjątkiem, że korzysta z ustawień regionalnych, przekazany w zamian.Aby uzyskać więcej informacji, zobacz Regionalne.

W języku C++ korzystając z tych funkcji jest uproszczona poprzez overloads szablonu; overloads można automatycznie rozpoznać długość buforu (eliminując konieczność należy określić argument rozmiar) i automatycznie można zastąpić starszych, które nie są bezpieczne funkcje z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
wcstombs_s	<stdlib.h>

Aby uzyskać dodatkowe informacje o zgodności, zobacz zgodności we wprowadzeniu.

Przykład

Ten program ilustruje zachowanie wcstombs_s funkcji.

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