mbstring(3C) DG/UX R4.11MU05 mbstring(3C)
NAME
mbstring: mbstowcs, wcstombs, mbsrtowcs, wcsrtombs - multibyte string
functions
SYNOPSIS
#include <stdlib.h>
sizet mbstowcs(wchart *pwcs, const char *s, sizet n);
sizet wcstombs(char *s, const wchart *pwcs, sizet n);
#include <wchar.h>
sizet mbsrtowcs(wchart *pwcs, const char **s, sizet n,
mbstatet *ps);
sizet wcsrtombs(char *s, const wchart **pwcs, sizet n,
mbstatet *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
(sizet)-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 (sizet)-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 (sizet)-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 (sizet)-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.
Considerations for Threads Programming
+----------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+----------+-----------------------------+
|mbsrtowcs | Y N N |
|mbstowcs | Y N N |
|wcsrtombs | Y N N |
|wcstombs | Y N N |
+----------+-----------------------------+
REFERENCES
wchrtbl(1M), mbchar(3C), reentrant(3), setlocale(3C), environ(5),
wchar(5)
Licensed material--property of copyright holder(s)