NAME    [Toc]    [Back]

       mbstowcs, mbsrtowcs - Convert a multibyte character string
       to a wide-character string

SYNOPSIS    [Toc]    [Back]

       #include <stdlib.h>

       size_t mbstowcs(
               wchar_t *pwcs,
               const char *s,
               size_t n ); #include <wchar.h>

       size_t mbsrtowcs(
               wchar_t *pwcs,
               const char **s,
               size_t n,
               mbstate_t *ps );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards as follows:

       mbstowcs(), mbsrtowcs(): XSH5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Points to the array where the result of the conversion  is
       stored.   Points  or  indirectly  points to the multibytecharacter
 string to be converted.  Specifies the number of
       wide  characters  in  the destination array.  Points to an
       mbstate_t structure containing the conversion state of the
       multibyte character in s (for mbrtowc() only).

DESCRIPTION    [Toc]    [Back]

       The  mbstowcs()  function  converts  a multibyte-character
       string into a wide-character string, which is stored at  a
       specified  location. The function does not examine or convert
 any characters that follow a null byte, which is converted
  and  stored  as  a  wide-character code with value
       zero. The function does not store more than n wide characters
  in  pwcs. When operating on overlapping strings, the
       behavior of this function is undefined.

       Behavior of the mbstowcs() function  is  affected  by  the
       LC_CTYPE  category  of the current locale. In locales that
       use shift-state encoding, the array pointed to  by  the  s
       parameter begins in the initial shift state.

       The  mbsrtowcs()  function  is  a  restartable  version of
       mbstowcs(). Restartable conversion  functions  obtain  and
       store  the conversion state in an mbstate_t structure that
       can be read and changed by subsequent calls to the same or
       other restartable conversion functions.

RESTRICTIONS    [Toc]    [Back]

       [Tru64  UNIX]  The  mbsrtowcs() and other restartable versions
 of conversion functions  are  functional  only  when
       used  with locales that support shift-state encoding. Currently,
 the operating system does not provide any  locales
       that  support  shift-state encoding, so the mbstowcs() and
       mbsrtowcs() functions do not differ in terms  of  run-time
       behavior.

RETURN VALUES    [Toc]    [Back]

       When the mbstowcs() and mbsrtowcs() functions encounter an
       invalid multibyte character during conversion, they return
       a value of -1 cast to size_t and set errno to indicate the
       error. Otherwise: The mbstowcs() function returns the number
  of characters stored in the output array (or required
       if pwcs is null), not including a  terminating  null  wide
       character,  if any. When the return value is n, the output
       array is not null-terminated.   The  mbsrtowcs()  function
       returns  the  number  of  characters  stored in the output
       array, not including a terminating null wide character, if
       any.

ERRORS    [Toc]    [Back]

       If  the  following  condition  occurs,  the mbstowcs() and
       mbsrtowcs()  functions  set  errno  to  the  corresponding
       value: The s parameter contains an invalid multibyte character.

SEE ALSO    [Toc]    [Back]

       Functions:  btowc(3),  mblen(3),  mbsinit(3),   mbtowc(3),
       wcstombs(3), wcslen(3), wctob(3), wctomb(3)



                                                      mbstowcs(3)