wcsrtombs - convert a wide character string to a multibyte
       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 con­
       verts 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 effec­
       tively    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 reasons:

       1.  A  wide character has been encountered that can not be
       represented as a multibyte sequence (according to the cur­
       rent  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  converted,
       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 character
       was encountered which could not be converted, (size_t)(-1)
       is returned, and errno set to EILSEQ.

       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.


Man(1) output converted with man2html