mbstring(S)

mbstring: mbstowcs, wcstombs, mbsrtowcs, wcsrtombs -- multibyte string functions

Synopsis

   #include <stdlib.h>
   
   size_t mbstowcs(wchar_t pwcs, const char s, size_t n);
   

   size_t wcstombs(char s, const wchar_t pwcs, size_t n);
   

   #include <wchar.h>
   

   size_t mbsrtowcs(wchar_t pwcs, const char s, size_t n,
                      mbstate_t ps);
   

   size_t wcsrtombs(char s, const wchar_t pwcs, size_t n,
                      mbstate_t ps);

Description

mbstowcs converts a sequence of multibyte characters from the array pointed to by s into a sequence of corresponding wide character codes and stores these codes into the array pointed to by pwcs, stopping after n codes are stored or a code with value zero (a converted null character) is stored.

wcstombs converts a sequence of wide character codes from the array pointed to by pwcs into a sequence of multibyte characters and stores these multibyte characters into the array pointed to by s, stopping if a multibyte character would exceed the limit of n total bytes or if a null character is stored. When s is a null pointer, then a call to wcstombs (s, pwcs, n) returns the number of bytes required to store the converted string, excluding the terminating null byte.

mbsrtowcs converts a sequence of multibyte characters that begins in the shift state described by ps from the array indirectly pointed to by s into a sequence of corresponding wide characters, which, if pwcs is not a null pointer, are then stored into the array pointed to by pwcs. Conversion continues up to and including a terminating null character, but the terminating null wide character will not be stored. Conversion stops prematurely in two cases: when a sequence of bytes is reached that does not form a valid multibyte character, or (if pwcs is not a null pointer) when n codes have been stored into the array pointed to by pwcs. Thus, the value of n is ignored if pwcs is a null pointer. Each conversion takes place as if by a call to the mbrtowc function.

If pwcs is not a null pointer, the pointer object pointed to by s is assigned either a null pointer (if conversion stopped due to reaching a terminating null character) or the address just past the last multibyte character converted. If conversion stopped due to reaching a terminating null character and if pwcs is not a null pointer, the resulting state described will be the initial conversion state.

wcsrtombs converts a sequence of wide characters from the array indirectly pointed to by pwcs into a sequence of corresponding multibyte characters that begins in the shift state described by ps, which, if s is not a null pointer, are then stored into the array pointed to by s. Conversion continues up to and including a terminating null wide character, but the terminating null character (byte) is not stored. Conversion stops prematurely in two cases: when a code is reached that does not correspond to a valid multibyte character, or (if s is not a null pointer) when the next multibyte character does exceed the limit of n total bytes to be stored into the array pointed to by s. Each conversion takes place as if by a call to the wcrtomb.

If s is not a null pointer, the pointer object pointed to by pwcs is assigned either a null pointer (if conversion stopped due to reaching a terminating null wide character) or the address just past the last wide character converted. If conversion stopped due to reaching a terminating null wide character and if s is not a null pointer, the resulting state described is the initial conversion state.

Return values

If an invalid multibyte character is encountered, mbstowcs returns (size_t)-1. Otherwise, mbstowcs returns the number of array elements modified, not including the terminating zero code, if any. If pwcs is a null pointer, mbstowcs returns the number of elements required for the wide character code array.

If a wide character code is encountered that does not correspond to a valid multibyte character, wcstombs returns (size_t)-1. Otherwise, wcstombs returns the number of bytes modified, not including a terminating null character, if any. If s is a null pointer, wcstombs returns the number of bytes required for the character array.

If the input string does not begin with a valid multibyte character, an encoding error occurs for mbsrtowcs. In this case, it stores the value of the macro EILSEQ in errno and returns (size_t)-1, but the conversion state is unchanged. Otherwise, it returns the number of multibyte characters successfully converted, which is the same as the number of array elements modified when s is not a null pointer.

If the first code is not a valid wide character, an encoding error occurs for wcsrtombs. In this case, it stores the value of the macro EILSEQ in errno and returns (size_t)-1, but the conversion state is unchanged. Otherwise, it returns the number of bytes in the resulting multibyte characters sequence, which is the same as the number of array elements modified when s is not a null pointer.

References

environ(M), mbchar(S), setlocale(S), wchar(M), wchrtbl(ADM)