NAME
wcrtomb() — convert a wide-character code to a character (restartable)
SYNOPSIS
#include <wchar.h>
size_t wcrtomb(char *s, wchar_t wc, mbstate_t *ps);
DESCRIPTION
If
s
is a null pointer, the
wcrtomb()
function is equivalent to the call:
where
buf
is an internal buffer.
If
s
is not a null pointer, the
wcrtomb()
function determines the number of bytes needed to represent the character
that corresponds to the wide-character given by
wc
(including any shift sequences),
and stores the resulting bytes in the array whose first element is
pointed to by
s.
At most
MB_CUR_MAX
bytes are stored.
If
wc
is a null wide-character, a null byte is stored, preceded by any shift
sequence needed to restore the initial shift state.
The resulting state described is the initial conversion state.
If
ps
is a null pointer, the
wcrtomb()
function uses its own internal
mbstate_t
object, which is initialized
at program startup to the initial conversion state.
Otherwise, the
mbstate_t
object pointed to by
ps
is used to completely describe the current conversion state of
the associated character sequence.
The implementation will behave as if no function defined in this
specification calls
wcrtomb().
EXTERNAL INFLUENCES
locale
The behavior of this function is affected by the
LC_CTYPE
category of the current locale.
RETURN VALUE
The
wcrtomb()
function returns the number of bytes stored in the array object
(including any shift sequences).
When
wc
is not a valid wide-character, an encoding error occurs.
In this case, the function stores the value of the macros
EILSEQ
in
errno
and returns
(size_t)-1;
the conversion state is undefined.
ERRORS
The
wcrtomb()
function may fail if:
- [EINVAL]
ps
points to an object that contains an invalid conversion state.
- [EILSEQ]
Invalid wide-character code is detected.
AUTHOR
wcrtomb()
was developed by HP and Mitsubishi Electric Corporation.
