huschi.net

MBSRTOWCS(3P)              POSIX Programmer's Manual             MBSRTOWCS(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
       mbsrtowcs - convert a  character  string  to  a  wide-character  string
       (restartable)
SYNOPSIS
       #include <wchar.h>
       size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,
              size_t len, mbstate_t *restrict ps);

DESCRIPTION
       The mbsrtowcs() function shall convert a sequence of characters, begin-
       ning in the conversion state described by the object pointed to by  ps,
       from  the  array indirectly pointed to by src into a sequence of corre-
       sponding wide characters. If dst is not a null pointer,  the  converted
       characters  shall  be stored into the array pointed to by dst.  Conver-
       sion continues up to and including a terminating null character,  which
       shall also be stored. Conversion shall stop early in either of the fol-
       lowing cases:
        * A sequence of bytes is encountered that does not form a valid  char-
          acter.
        * len codes have been stored into the array pointed to by dst (and dst
          is not a null pointer).
       Each conversion shall take place as if by a call to the mbrtowc() func-
       tion.
       If  dst  is  not  a  null pointer, the pointer object pointed to by src
       shall be assigned either a null pointer (if conversion stopped  due  to
       reaching  a  terminating  null  character) or the address just past the
       last character converted (if any). If conversion stopped due to  reach-
       ing a terminating null character, and if dst is not a null pointer, the
       resulting state described shall be the initial conversion state.
       If ps is a null pointer, the mbsrtowcs() 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  behaves
       as  if no function defined in this volume of IEEE Std 1003.1-2001 calls
       mbsrtowcs().
       The behavior of this function shall be affected by the  LC_CTYPE  cate-
       gory of the current locale.
RETURN VALUE
       If the input conversion encounters a sequence of bytes that do not form
       a valid character, an encoding error occurs. In this  case,  the  mbsr-
       towcs()  function  stores  the value of the macro [EILSEQ] in errno and
       shall return (size_t)-1; the conversion state is undefined.  Otherwise,
       it  shall  return  the number of characters successfully converted, not
       including the terminating null (if any).
ERRORS
       The mbsrtowcs() function may fail if:
       EINVAL ps points to an  object  that  contains  an  invalid  conversion
              state.
       EILSEQ Invalid character sequence is detected.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       None.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       mbsinit(),     mbrtowc(),    the    Base    Definitions    volume    of
       IEEE Std 1003.1-2001, <wchar.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                        MBSRTOWCS(3P)