# wcsnrtombs

## NAME



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


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <wchar.h>**
    
           **size_t wcsnrtombs(** size_t size;
                             **char** _dest_**[restrict** _size_**], const wchar_t **restrict** _src_**,**
                             **size_t** _nwc_**, size_t** _size_**, mbstate_t *restrict** _ps_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **wcsnrtombs**():
               Since glibc 2.10:
                   _POSIX_C_SOURCE >= 200809L
               Before glibc 2.10:
                   _GNU_SOURCE
    


## DESCRIPTION



           The **wcsnrtombs**() function is like the wcsrtombs(3) function,
           except that the number of wide characters to be converted,
           starting at _*src_ , is limited to _nwc_.
    
           If _dest_ is not NULL, the **wcsnrtombs**() function converts at most
           _nwc_ wide characters from 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**.
    
           •  _nwc_ wide characters have been converted without encountering a
              null wide character (L'\0'), or 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 (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 destination size limit exists.
    
           In both of the above cases, if _ps_ is NULL, a static anonymous
           state known only to the **wcsnrtombs**() function is used instead.
    
           The programmer must ensure that there is room for at least _size_
           bytes at _dest_.
    


## RETURN VALUE



           The **wcsnrtombs**() 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** │
           ├──────────────┼───────────────┼─────────────────────────────────┤
           │ **wcsnrtombs**() │ Thread safety │ MT-Unsafe race:wcsnrtombs/!ps   │
           └──────────────┴───────────────┴─────────────────────────────────┘
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



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


* * *