# wcrtomb

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           wcrtomb — convert a wide-character code to a character
           (restartable)
    


## SYNOPSIS



           #include <wchar.h>
    
           size_t wcrtomb(char *restrict _s_ , wchar_t _wc_ , mbstate_t *restrict _ps_);
    


## DESCRIPTION



           The functionality described on this reference page is aligned with
           the ISO C standard. Any conflict between the requirements
           described here and the ISO C standard is unintentional. This
           volume of POSIX.1‐2017 defers to the ISO C standard.
    
           If _s_ is a null pointer, the _wcrtomb_() function shall be equivalent
           to the call:
    
               wcrtomb(_buf_ , L'\0', _ps_)
    
           where _buf_ is an internal buffer.
    
           If _s_ is not a null pointer, the _wcrtomb_() function shall determine
           the number of bytes needed to represent the character that
           corresponds to the wide character given by _wc_ (including any shift
           sequences), and store the resulting bytes in the array whose first
           element is pointed to by _s_.  At most {MB_CUR_MAX} bytes are
           stored. If _wc_ is a null wide character, a null byte shall be
           stored, preceded by any shift sequence needed to restore the
           initial shift state. The resulting state described shall be the
           initial conversion state.
    
           If _ps_ is a null pointer, the _wcrtomb_() function shall use its own
           internal **mbstate_t** object, which is initialized at program start-
           up to the initial conversion state. Otherwise, the **mbstate_t**
           object pointed to by _ps_ shall be used to completely describe the
           current conversion state of the associated character sequence. The
           implementation shall behave as if no function defined in this
           volume of POSIX.1‐2017 calls _wcrtomb_().
    
           The _wcrtomb_() function need not be thread-safe if called with a
           NULL _ps_ argument.
    
           The behavior of this function shall be affected by the _LC_CTYPE_
           category of the current locale.
    
           The _wcrtomb_() function shall not change the setting of _errno_ if
           successful.
    


## RETURN VALUE



           The _wcrtomb_() function shall return the number of bytes stored in
           the array object (including any shift sequences). When _wc_ is not a
           valid wide character, an encoding error shall occur. In this case,
           the function shall store the value of the macro **[EILSEQ]** in _errno_
           and shall return (**size_t**)-1; the conversion state shall be
           undefined.
    


## ERRORS



           The _wcrtomb_() function shall fail if:
    
           **EILSEQ** An invalid wide-character code is detected.
    
           The _wcrtomb_() function may fail if:
    
           **EINVAL** _ps_ points to an object that contains an invalid conversion
                  state.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *