Udostępnij za pośrednictwem

wcstombs_s, _wcstombs_s_l

  • Artykuł

Konwertuje sekwencję znaków szerokich na odpowiadającą sekwencję znaków wielobajtowych. Wersja programu z ulepszeniami zabezpieczeń wcstombs _wcstombs_lzgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Składnia

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

pReturnValue
Rozmiar w bajtach przekonwertowanego ciągu, w tym terminator o wartości null.

mbstr
Adres buforu dla wynikowego przekonwertowanego ciągu znaków wielobajtowych.

sizeInBytes
Rozmiar w bajtach buforu mbstr .

wcstr
Wskazuje ciąg znaków szeroki do przekonwertowania.

count
Maksymalna liczba bajtów do przechowania w buforze mbstr , bez uwzględniania znaku zerowego zakończenia lub _TRUNCATE.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zero, jeśli działanie powiedzie się, kod błędu w przypadku niepowodzenia.

Błąd Wartość zwracana i errno
mbstr is NULL i sizeInBytes> 0 EINVAL
wcstr jest NULL EINVAL
Bufor docelowy jest za mały, aby zawierał przekonwertowany ciąg (chyba że count jest _TRUNCATEto ; zobacz uwagi poniżej) ERANGE

Jeśli wystąpi którykolwiek z tych warunków, jest wywoływany nieprawidłowy wyjątek parametru zgodnie z opisem w temacie Walidacja parametru. Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja zwraca kod błędu i ustawia je errno zgodnie z opisem w tabeli.

Uwagi

Funkcja wcstombs_s konwertuje ciąg znaków szerokich znaków wskazywanych na wcstr znaki wielobajtowe przechowywane w buforze wskazywanym przez mbstr. Konwersja będzie kontynuowana dla każdego znaku do momentu spełnienia jednego z następujących warunków:

  • Napotkano znak szeroki o wartości null

  • Napotkano szeroki znak, którego nie można przekonwertować

  • Liczba bajtów przechowywanych w buforze mbstr jest countrówna .

Ciąg docelowy jest zawsze zakończony wartością null (nawet jeśli wystąpi błąd).

Jeśli count jest to wartość _TRUNCATEspecjalna, funkcja wcstombs_s konwertuje tyle ciągu, jak będzie mieścić się w buforze docelowym, pozostawiając miejsce na terminator o wartości null. Jeśli ciąg zostanie obcięty, zwracana wartość to STRUNCATE, a konwersja zostanie uznana za pomyślną.

Jeśli wcstombs_s ciąg źródłowy zostanie pomyślnie przekonwertowany, umieści rozmiar w bajtach przekonwertowanego ciągu, w tym terminator o wartości null, na *pReturnValue wartość (podany pReturnValue nie NULLjest ). Rozmiar jest obliczany nawet wtedy, gdy mbstr argument to NULL; umożliwia określenie wymaganego rozmiaru buforu. Jeśli mbstr wartość to NULL, count jest ignorowana.

Jeśli wcstombs_s napotka szeroki znak, nie może przekonwertować na znak wielobajtowy, umieszcza wartość 0 w *ReturnValue, ustawia bufor docelowy na pusty ciąg, ustawia errno wartość EILSEQna , i zwraca wartość EILSEQ.

Jeśli sekwencje wskazywane przez wcstr i mbstr nakładają się na siebie, zachowanie wcstombs_s jest niezdefiniowane.

Ważne

Upewnij się, że wcstr i mbstr nie nakładają się, i że count poprawnie odzwierciedla liczbę znaków szerokich do przekonwertowania.

wcstombs_s używa bieżących ustawień regionalnych dla dowolnego zachowania zależnego od ustawień regionalnych; _wcstombs_s_l jest identyczna z wcstombs tą różnicą, że używa ustawień regionalnych przekazanych w zamian. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++używanie tych funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Wymagania

Procedura Wymagany nagłówek
wcstombs_s <stdlib.h>

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

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 );
    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.

Zobacz też

Konwersja danych
ustawienia regionalne
_mbclen, , mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte