huschi.net

MBTOWC(3P)                 POSIX Programmer's Manual                MBTOWC(3P)

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
       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 unspec-
       ified. 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 vol-
       ume of IEEE Std 1003.1-2001 calls mbtowc().
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 con-
       stitute the converted character (if the next n or fewer  bytes  form  a
       valid character), or return -1  and may 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 may fail if:
       EILSEQ Invalid character sequence is detected.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       None.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       mblen(),  mbstowcs(), wctomb(), wcstombs(), the Base Definitions volume
       of IEEE Std 1003.1-2001, <stdlib.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                           MBTOWC(3P)