mbstring(3C) mbstring(3C)
NAME
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.
Copyright 1994 Novell, Inc. Page 1
mbstring(3C) mbstring(3C)
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.
Copyright 1994 Novell, Inc. Page 2
mbstring(3C) mbstring(3C)
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(5), mbchar(3C), setlocale(3C), wchar(5), wchrtbl(1M)
Copyright 1994 Novell, Inc. Page 3