# mbtowc

## 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



           mbtowc — convert a character to a wide-character code
    


## SYNOPSIS



           #include <stdlib.h>
    
           int mbtowc(wchar_t *restrict _pwc_ , const char *restrict _s_ , size_t _n_);
    


## 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 not a null pointer, _mbtowc_() shall determine the number of
           bytes that constitute the character pointed to by _s_.  It shall
           then determine the wide-character code for the value of type
           **wchar_t** that corresponds to that character. (The value of the
           wide-character code corresponding to the null byte is 0.) If the
           character is valid and _pwc_ is not a null pointer, _mbtowc_() shall
           store the wide-character code in the object pointed to by _pwc_.
    
           The behavior of this function is affected by the _LC_CTYPE_ category
           of the current locale. For a state-dependent encoding, this
           function is placed into its initial state by a call for which its
           character pointer argument, _s_ , is a null pointer. Subsequent calls
           with _s_ as other than a null pointer shall cause the internal state
           of the function to be altered as necessary. A call with _s_ as a
           null pointer shall cause this function to return a non-zero value
           if encodings have state dependency, and 0 otherwise. If the
           implementation employs special bytes to change the shift state,
           these bytes shall not produce separate wide-character codes, but
           shall be grouped with an adjacent character. Changing the _LC_CTYPE_
           category causes the shift state of this function to be
           unspecified. At most _n_ bytes of the array pointed to by _s_ shall be
           examined.
    
           The implementation shall behave as if no function defined in this
           volume of POSIX.1‐2017 calls _mbtowc_().
    
           The _mbtowc_() function need not be thread-safe.
    


## RETURN VALUE



           If _s_ is a null pointer, _mbtowc_() shall return a non-zero or 0
           value, if character encodings, respectively, do or do not have
           state-dependent encodings. If _s_ is not a null pointer, _mbtowc_()
           shall either return 0 (if _s_ points to the null byte), or return
           the number of bytes that constitute the converted character (if
           the next _n_ or fewer bytes form a valid character), or return -1
           and shall set _errno_ to indicate the error (if they do not form a
           valid character).
    
           In no case shall the value returned be greater than _n_ or the value
           of the {MB_CUR_MAX} macro.
    


## ERRORS



           The _mbtowc_() function shall fail if:
    
           **EILSEQ** An invalid character sequence is detected. In the POSIX
                  locale an **[EILSEQ]** error cannot occur since all byte values
                  are valid characters.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *