# wcsrtombs

## NAME



           wcsrtombs - convert a wide-character string to a multibyte string
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <wchar.h>**
    
           **size_t wcsrtombs(** size_t size;
                            **char** _dest_**[restrict** _size_**], const wchar_t **restrict** _src_**,**
                            **size_t** _size_**, mbstate_t *restrict** _ps_**);**
    


## DESCRIPTION



           If _dest_ is not NULL, the **wcsrtombs**() function converts the wide-
           character string _*src_ to a multibyte string starting at _dest_.  At
           most _size_ bytes are written to _dest_.  The shift state _*ps_ is
           updated.  The conversion is effectively performed by repeatedly
           calling _wcrtomb(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:
    
           •  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**.
    
           •  The size 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.
    
           •  The wide-character string has been completely converted,
              including the terminating null wide character (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 null byte ('\0'), is
              returned.
    
           If _dest_ is NULL, _size_ is ignored, and the conversion proceeds as
           above, except that the converted bytes are not written out to
           memory, and that no size limit exists.
    
           In both of the above cases, if _ps_ is NULL, a static anonymous
           state known only to the **wcsrtombs**() function is used instead.
    
           The programmer must ensure that there is room for at least _size_
           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**.
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌─────────────┬───────────────┬──────────────────────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **wcsrtombs**() │ Thread safety │ MT-Unsafe race:wcsrtombs/!ps     │
           └─────────────┴───────────────┴──────────────────────────────────┘
    


## STANDARDS



           C11, POSIX.1-2008.
    


## NOTES



           The behavior of **wcsrtombs**() depends on the **LC_CTYPE** category of
           the current locale.
    
           Passing NULL as _ps_ is not multithread safe.
    


* * *