mbstowcs_s, _mbstowcs_s_l

Konwertuje sekwencję znaków wielobajtowych na odpowiednią sekwencję znaków szerokich. Wersje programu mbstowcs _mbstowcs_lz ulepszeniami zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Składnia

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parametry

pReturnValue
Liczba przekonwertowanych znaków.

wcstr
Adres buforu dla wynikowego przekonwertowanego ciągu znaków szerokiego.

sizeInWords
Rozmiar buforu wcstr w słowach.

mbstr
Adres sekwencji znaków wielobajtowych zakończonych o wartości null.

count
Maksymalna liczba znaków szerokich do przechowywania w buforze wcstr , w tym wartości null 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
wcstr is NULL i sizeInWords> 0	EINVAL
mbstr jest NULL	EINVAL
Bufor docelowy jest za mały, aby zawierał przekonwertowany ciąg (chyba że count jest _TRUNCATEto ; zobacz uwagi poniżej)	ERANGE
wcstr nie NULL jest i sizeInWords == 0	EINVAL

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 mbstowcs_s konwertuje ciąg znaków wielobajtowych wskazywanych przez na mbstr znaki szerokie przechowywane w buforze wskazywanym przez wcstr. Konwersja będzie kontynuowana dla każdego znaku do momentu spełnienia jednego z następujących warunków:

• Napotkano wielobajtowy znak o wartości null

• Napotkano nieprawidłowy znak wielobajtowy

• Liczba znaków szerokich przechowywanych w buforze wcstr 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 mbstowcs_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 mbstowcs_s ciąg źródłowy zostanie pomyślnie przekonwertowany, spowoduje to umieszczenie rozmiaru w szerokich znakach przekonwertowanego ciągu, w tym na terminator *pReturnValue o wartości null (podany pReturnValue nie NULLjest ). Rozmiar jest obliczany nawet wtedy, gdy wcstr argument to NULL, i umożliwia określenie wymaganego rozmiaru buforu. Jeśli wcstr parametr to NULL, count jest ignorowany i sizeInWords musi mieć wartość 0.

Jeśli mbstowcs_s napotka nieprawidłowy znak wielobajtowy, umieszcza wartość 0 w *pReturnValue, ustawia bufor docelowy na pusty ciąg, ustawia errno wartość EILSEQna , i zwraca wartość EILSEQ.

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

Ważne

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

mbstowcs_s używa bieżących ustawień regionalnych dla dowolnego zachowania zależnego od ustawień regionalnych; _mbstowcs_s_l jest identyczna, z 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
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

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

Zobacz też

Konwersja danych
ustawienia regionalne
MultiByteToWideChar
Interpretacja sekwencji znaków wielobajtowych
_mbclen, , mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l