# mbsrtowcs

## NAME



           mbsrtowcs - convert a multibyte string to a wide-character string
           (restartable)
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <wchar.h>**
    
           **size_t mbsrtowcs(** size_t dsize;
                            **wchar_t** _dest_**[restrict** _dsize_**],**
                            **const char **restrict** _src_**,**
                            **size_t** _dsize_**, mbstate_t *restrict** _ps_**);**
    


## DESCRIPTION



           If _dest_ is not NULL, convert the multibyte string _*src_ to a wide-
           character string starting at _dest_.  At most _dsize_ wide characters
           are written to _dest_.  The shift state _*ps_ is updated.  The
           conversion is effectively performed by repeatedly calling
           _mbrtowc(dest, *src, n, ps)_ where _n_ is some positive number, as
           long as this call succeeds, and then incrementing _dest_ by one and
           _*src_ by the number of bytes consumed.  The conversion can stop for
           three reasons:
    
           •  An invalid multibyte sequence has been encountered.  In this
              case, _*src_ is left pointing to the invalid multibyte sequence,
              _(size_t) -1_ is returned, and _errno_ is set to **EILSEQ**.
    
           •  _dsize_ non-L'\0' wide characters have been stored at _dest_.  In
              this case, _*src_ is left pointing to the next multibyte sequence
              to be converted, and the number of wide characters written to
              _dest_ is returned.
    
           •  The multibyte string has been completely converted, including
              the terminating null wide character ('\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 wide characters
              written to _dest_ , excluding the terminating null wide character,
              is returned.
    
           If _dest_ is NULL, _dsize_ is ignored, and the conversion proceeds as
           above, except that the converted wide characters are not written
           out to memory, and that no length limit exists.
    
           In both of the above cases, if _ps_ is NULL, a static anonymous
           state known only to the **mbsrtowcs**() function is used instead.
    
           In order to avoid the case 2 above, the programmer should make
           sure _dsize_ is greater than or equal to _mbsrtowcs(NULL,src,0,ps)+1_.
    
           The programmer must ensure that there is room for at least _dsize_
           wide characters at _dest_.
    
           This function is a restartable version of mbstowcs(3).
    


## RETURN VALUE



           The number of wide characters that make up the converted part of
           the wide-character string, not including the terminating null wide
           character.  If an invalid multibyte sequence was encountered,
           _(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** │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **mbsrtowcs**() │ Thread safety │ MT-Unsafe race:mbsrtowcs/!ps     │
           └─────────────┴───────────────┴──────────────────────────────────┘
    


## STANDARDS



           C11, POSIX.1-2008.
    


## NOTES



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


* * *