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

       mbsnrtowcs,   mbsrtowcs   —   convert  a  character  string  to  a  wide-character  string
       (restartable)

SYNOPSIS

       #include <wchar.h>

       size_t mbsnrtowcs(wchar_t *restrict dst, const char **restrict src,
           size_t nmc, size_t len, mbstate_t *restrict ps);
       size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,
           size_t len, mbstate_t *restrict ps);

DESCRIPTION

       For mbsrtowcs(): 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‐2008 defers to the ISO C standard.

       The mbsrtowcs() function  shall  convert  a  sequence  of  characters,  beginning  in  the
       conversion  state  described  by  the  object  pointed to by ps, from the array indirectly
       pointed to by src into a sequence of corresponding wide characters. If dst is not  a  null
       pointer,  the  converted  characters  shall  be  stored  into the array pointed to by dst.
       Conversion continues up to and including a terminating null character, which shall also be
       stored. Conversion shall stop early in either of the following cases:

        *  A sequence of bytes is encountered that does not form a valid character.

        *  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() function.

       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  reaching 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 mbsnrtowcs() function shall be equivalent to the mbsrtowcs() function, except that the
       conversion of characters pointed to by src is limited to at most nmc bytes  (the  size  of
       the input buffer).

       The  behavior of these functions shall be affected by the LC_CTYPE category of the current
       locale.

       The implementation shall behave as if no function defined in this volume  of  POSIX.1‐2008
       calls these functions.

       The  mbsnrtowcs()  and mbsrtowcs() functions need not be thread-safe if called with a NULL
       ps argument.

       The mbsrtowcs() function shall not change the setting of errno if successful.

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, these functions shall store the value of the macro
       [EILSEQ] in errno  and  shall  return  (size_t)−1;  the  conversion  state  is  undefined.
       Otherwise,  these  functions shall return the number of characters successfully converted,
       not including the terminating null (if any).

ERRORS

       These functions shall fail if:

       EILSEQ An invalid character sequence is detected.

       These functions 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.

SEE ALSO

       iconv(), mbrtowc(), mbsinit()

       The Base Definitions volume of POSIX.1‐2008, <wchar.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2013  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013  by  the
       Institute  of  Electrical  and  Electronics  Engineers,  Inc and The Open Group.  (This is
       POSIX.1-2008 with the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .