bionic (3) mbstowcs.3posix.gz

Provided by: manpages-posix-dev_2013a-2_all bug

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
       mbstowcs — convert a character string to a wide-character string


SYNOPSIS
       #include <stdlib.h>

       size_t mbstowcs(wchar_t *restrict pwcs, 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‐2008 defers to the ISO C standard.

       The  mbstowcs()  function  shall  convert a sequence of characters that begins in the initial shift state
       from the array pointed to by s into a sequence of corresponding wide-character codes and shall store  not
       more  than  n  wide-character  codes into the array pointed to by pwcs.  No characters that follow a null
       byte (which is converted into a wide-character code with value 0) shall be examined  or  converted.  Each
       character  shall be converted as if by a call to mbtowc(), except that the shift state of mbtowc() is not
       affected.

       No more than n elements shall be modified in the array pointed  to  by  pwcs.   If  copying  takes  place
       between objects that overlap, the behavior is undefined.

       The  behavior of this function shall be affected by the LC_CTYPE category of the current locale.  If pwcs
       is a null pointer, mbstowcs() shall return the length required to convert the entire array regardless  of
       the value of n, but no values are stored.


RETURN VALUE
       If  an  invalid  character  is  encountered,  mbstowcs()  shall  return (size_t)−1 and shall set errno to
       indicate the error.

       Otherwise, mbstowcs() shall return the number of the array elements modified  (or  required  if  pwcs  is
       null),  not  including  a terminating 0 code, if any. The array shall not be zero-terminated if the value
       returned is n.


ERRORS
       The mbstowcs() function shall fail if:

       EILSEQ An invalid byte sequence is detected.

       The following sections are informative.


EXAMPLES
       None.


APPLICATION USAGE
       None.


RATIONALE
       None.


FUTURE DIRECTIONS
       None.


SEE ALSO
       mblen(), mbtowc(), wctomb(), wcstombs()

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


       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 .