Index for Section 3

Alphabetical listing for M

Bottom of page

mbstowcs(3)
NAME
  mbstowcs, mbsrtowcs - Convert a multibyte character string to a wide-
  character string

SYNOPSIS
  #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
  Standard C Library (libc)

STANDARDS
  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
  *pwc
      Points to the array where the result of the conversion is stored.

  *s or **s
      Points or indirectly points to the multibyte-character string to be
      converted.

  n   Specifies the number of wide characters in the destination array.

  *ps Points to an mbstate_t structure containing the conversion state of the
      multibyte character in s (for mbrtowc() only).

DESCRIPTION
  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
  [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
  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
  If the following condition occurs, the mbstowcs() and mbsrtowcs() functions
  set errno to the corresponding value:

  [EILSEQ]
      The s parameter contains an invalid multibyte character.

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

Index for Section 3

Alphabetical listing for M

Top of page