mbstowcs_s, _mbstowcs_s_l

Artykuł
06/09/2015

Konwertuje sekwencja znaków wielobajtowych odpowiednich sekwencja znaków szerokości.Wersje mbstowcs, _mbstowcs_l z rozszerzeń zabezpieczeń opisane w Funkcje zabezpieczeń w CRT.

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

[out]pReturnValue
Liczby konwertowane znaki.
[out]wcstr
Adres buforu dla wynikowy ciąg przekonwertowany szerokich znaków.
[w]sizeInWords
Rozmiar wcstr buforu w słowach.
[w]mbstr
Adres sekwencji null zakończone znaki wielobajtowe.
[w]count
Maksymalna liczba znaków szerokości do przechowywania w wcstr buforu, nie włączając zakończeń 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
wcstris NULL and sizeInWords > 0	EINVAL
mbstrjestNULL	EINVAL
Bufor docelowy jest zbyt mały, aby zawierać ciąg przekonwertowany (chyba że count jest _TRUNCATE; Zobacz uwagi poniżej)	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

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

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

Po napotkaniu wielobajtowych znakiem null
Napotka nieprawidłowych znaków wielobajtowych
Liczba szerokości znaków przechowywanych w wcstr 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 mbstowcs_s konwertuje tyle ciągu będą mieści się w bufor docelowy, pozostawiając nadal miejsca na null terminator.

Jeśli mbstowcs_s pomyślnie konwertuje ciąg źródłowy umieszcza w szerokości znaków ciągu przekonwertowane, łącznie null terminator do rozmiaru *pReturnValue (pod warunkiem pReturnValue nie jest NULL).Dzieje się tak nawet wtedy, gdy wcstr argument jest NULL i zapewnia sposób określić wymagany rozmiar buforu.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

Jeśli mbstowcs_s napotka nieprawidłowych znaków wielobajtowych umieszcza 0 w *pReturnValue, ustawia bufor docelowy ciąg pusty, ustawia errno do EILSEQi zwraca EILSEQ.

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

Uwaga dotycząca zabezpieczeń
Zapewnić, że wcstr i mbstr nie nakładają się i że count poprawnie odzwierciedla liczbę znaków wielobajtowych do konwersji.

mbstowcs_swykorzystuje bieżące ustawienia regionalne dla dowolnego zachowanie zależne od ustawień regionalnych; _mbstowcs_s_ljest identyczny z tym, ż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.