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



NAME
       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.

CONFORMING TO
       ISO/ANSI C, UNIX98

SEE ALSO
       wcstombs(s), wcsnrtombs(s), iconv(v)

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                         1999-07-25               WCSRTOMBS(S)