mbtowc(3C)




NAME

     mbtowc - convert a character to a wide-character code


SYNOPSIS

     #include <stdlib.h>

     int mbtowc(wchar_t *pwc, const char *s, size_t n);


DESCRIPTION

     If s is not a null pointer, mbtowc() determines  the  number
     of  the bytes that constitute the character pointed to by s.
     It then determines 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()  stores  the  wide-character  code  in  the  object
     pointed to by pwc.

     A call with s as a null  pointer  causes  this  function  to
     return  0.  The behavior of this function is affected by the
     LC_CTYPE category of the current locale. At most n bytes  of
     the array pointed to by s will be examined.


RETURN VALUES

     If s is a null pointer, mbtowc() returns 0. If s  is  not  a
     null  pointer,  mbtowc()  returns 0 (if s points to the null
     byte), the number of bytes  that  constitute  the  converted
     character (if the next n or fewer bytes form a valid charac-
     ter), or  -1 and may set errno to  indicate  the  error  (if
     they do not form a valid character).

     In no case will the value returned be greater than n or  the
     value of the MB_CUR_MAX macro.


ERRORS

     The mbtowc() function may fail if:

     EILSEQ
           Invalid character sequence is detected.


USAGE

     The mbtowc() function can be used  safely  in  multithreaded
     applications,  as  long as setlocale(3C) is not being called
     to change the locale.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe with exceptions     |
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|


SEE ALSO

     mblen(3C),   mbstowcs(3C),   setlocale(3C),    wcstombs(3C),
     wctomb(3C), attributes(5)


Man(1) output converted with man2html