WCSRTOMBS(3)       Linux Programmer's Manual       WCSRTOMBS(3)





NAME
       wcsrtombs  - convert a wide character string to a multi-
       byte string

SYNOPSIS
       #include <wchar.h>

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

DESCRIPTION
       If dest is not a NULL pointer,  the  wcsrtombs  function
       converts  the  wide-character string *src to a multibyte
       string starting at dest. At most len bytes  are  written
       to  dest. The shift state *ps is updated. The conversion
       is effectively  performed  by  repeatedly  calling  wcr-
       tomb(dest,*src,ps),  as  long as this call succeeds, and
       then incrementing dest by the number  of  bytes  written
       and  *src by one. The conversion can stop for three rea-
       sons:

       1. A wide character has been encountered that can not be
       represented  as  a  multibyte sequence (according to the
       current locale). In this case *src is left  pointing  to
       the  invalid  wide  character, (size_t)(-1) is returned,
       and errno is set to EILSEQ.

       2. The length limit forces a stop. In this case *src  is
       left  pointing  to  the  next  wide character to be con-
       verted, and the number  of  bytes  written  to  dest  is
       returned.

       3.  The  wide-character  string has been completely con-
       verted, including the terminating L'\0' (which  has  the
       side  effect of bringing back *ps to the initial state).
       In this case *src is set to  NULL,  and  the  number  of
       bytes  written  to  dest, excluding the terminating '\0'
       byte, is returned.

       If dest is NULL, len is ignored, and the conversion pro-
       ceeds  as above, except that the converted bytes are not
       written out to memory, and that no length limit  exists.

       In  both  of the above cases, if ps is a NULL pointer, a
       static anonymous state only known to the wcsrtombs func-
       tion is used instead.

       The  programmer  must  ensure  that there is room for at
       least len bytes at dest.

RETURN VALUE
       The wcsrtombs function returns the number of bytes  that
       make  up  the  converted part of multibyte sequence, not
       including the terminating null byte.  If a wide  charac-
       ter  was  encountered  which  could  not  be  converted,
       (size_t)(-1) is returned, and errno set to EILSEQ.

CONFORMING TO
       ISO/ANSI C, UNIX98

SEE ALSO
       wcstombs(3), wcsnrtombs(3), iconv(3)

NOTES
       The behaviour of wcsrtombs depends on the LC_CTYPE cate-
       gory of the current locale.

       Passing NULL as ps is not multi-thread safe.



GNU                      July 25, 1999             WCSRTOMBS(3)
