HELPLIB.HLB  —  CRTL  wcsrtombs
    Converts a sequence of wide characters into a sequence of
    corresponding multibyte characters.

    Format

      #include  <wchar.h>

      size_t wcsrtombs  (char *dst, const wchar_t **src, size_t len,
                        mbstate_t *ps);

1  –  Function Variants

    The wcsrtombs function has variants named _wcsrtombs32 and
    _wcsrtombs64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

2  –  Arguments

 dst

    A pointer to the destination array for converted multibyte
    character sequence.

 src

    An address of the pointer to an array containing the sequence of
    wide characters to be converted.

 len

    The maximum number of bytes that can be stored in the array
    pointed to by dst.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

3  –  Description

    The wcsrtombs function converts a sequence of wide characters
    from the array indirectly pointed to by src into a sequence of
    corresponding multibyte characters, beginning in the conversion
    state described by the object pointed to by ps.

    If dst is a not a NULL pointer, the converted characters are then
    stored into the array pointed to by dst. Conversion continues up
    to and including a terminating null wide character, which is also
    stored.

    Conversion stops earlier in two cases:

    o  When a code is reached that does not correspond to a valid
       multibyte character

    o  If dst is not a NULL pointer, when the next multibyte
       character would exceed the limit of len total bytes to be
       stored into the array pointed to by dst

    Each conversion takes place as if by a call to the wcrtomb
    function.

    If dst is not a NULL pointer, the pointer object pointed to by
    src is assigned either a NULL pointer (if the conversion stopped
    because it reached a terminating null wide character) or the
    address just beyond the last wide character converted (if any).
    If conversion stopped because it reached a terminating null
    wide character, the resulting state described is the initial
    conversion state.

    If the wcsrtombs function is called as a counting function,
    which means that dst is a NULL pointer, the value of the internal
    mbstate_t object will remain unchanged.

    See also wcrtomb.

4  –  Return Values

    x                  The number of bytes stored in the resulting
                       array, not including the terminating null (if
                       any).
    -1                 Indicates an encoding error-a character that
                       does not correspond to a valid multibyte
                       character was encountered; errno is set to
                       EILSEQ; the conversion state is undefined.
Close Help