Index for Section 3

Alphabetical listing for M

Bottom of page

mbtowc(3)
NAME
  mbtowc, mbrtowc - Convert a multibyte character to a wide character

SYNOPSIS
  #include <stdlib.h>

  int mbtowc(
	  wchar_t *pwc,
	  const char *s,
	  size_t n );

  #include <wchar.h>

  size_t mbrtowc(
	  wchar_t *pwc,
	  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:

  mbtowc(): ISO C, XPG4

  mbrtowc(): ISO C

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

PARAMETERS
  *pwc
      Points to the location of a variable containing the wide-character
      value.

  *s  Points to a byte array containing the multibyte character to be
      converted.

  n   Specifies the maximum number of bytes to evaluate.

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

DESCRIPTION
  The mbtowc() function converts a multibyte character to a wide character
  and returns the number of bytes of the multibyte character, which is stored
  as an output variable.

  In locales with shift-state character encoding, a call to mbtowc() with a
  null pointer as the s parameter places the function in the initial shift
  state. A call to mbtowc() with an s parameter that is not a null pointer
  may change the shift state for subsequent calls to mbtowc(), depending on
  the character examined. Changing the LC_CTYPE category of the locale causes
  the shift state of the function to be indeterminate. The implementation
  behaves as though no other function calls the mbtowc() function.

  In the case of nonrestartable functions, such as mbtowc(), conversion of
  shift-state encoding must first be enabled by calling the function with a
  null pointer parameter and then calling the function again with the
  multibyte value to be converted. The status of the conversion operation
  after the call is not available to subsequent calls.

  The mbrtowc() function is a restartable version of mbtowc(), which means
  that the shift state for the character in s is maintained in the mbstate_t
  structure and is therefore available to subsequent calls by mbrtowc() and
  other restartable conversion functions.

RESTRICTIONS
  The mbrtowc() and other restartable conversion routines are functional only
  when used with locales that support shift-state encoding.  Currently, the
  Tru64 UNIX product does not provide locales that use shift-state encoding.
  Therefore, the run-time behavior of mbrtowc() is equivalent to mbtowc(),
  and neither function returns values listed for state-dependent conditions.

RETURN VALUES
  If *s is not a null pointer, the mbtowc() function returns the following
  values:

    ·  A positive value indicating the number of bytes in the multibyte
       character, if the next n or fewer bytes in s constitutes a valid
       multibyte character other than the null character

    ·  Zero, if s contains a null character

    ·  -1, if s does not contain a valid multibyte character or contains a
       character having more than the number of bytes expressed by the n
       parameter. In this case, mbtowc() sets errno to indicate the error.

  If s is not a null pointer, the mbrtowc() function returns the first value
  that applies in the following list:

    ·  Zero, if the next n or fewer bytes are converted to a null wide
       character, which is then stored in pwc

    ·  A positive value indicating the number of bytes in the converted
       multibyte character, if the next n or fewer bytes constitute a valid
       multibyte character. The counterpart wide-character value is then
       stored in pwc.

    ·  (size_t)-2, if the next n bytes contribute to an incomplete (but
       potentially valid) multibyte character. In this case, no value is
       stored in pwc.

    ·  (size_t)-1, if an encoding error occurs, in which case the next n or
       fewer bytes do not contribute to a complete and valid multibyte
       character. In this case, no value is stored in pwc, the function sets
       errno to EILSEQ, and the conversion state is undefined.

  If *s is a null pointer, both the mbtowc() and mbrtowc() functions return
  one of the following values, depending on whether the character encoding in
  the current locale is shift-state dependent:

    ·  A nonzero value, if the character encoding is shift-state dependent

    ·  Zero, if the character encoding is not shift-state dependent

  The return values for these functions is never greater than the value
  specified by the n parameter or the value of MB_CUR_MAX.

ERRORS
  If the following condition occurs, the mbtowc() and mbrtowc() functions set
  errno to the corresponding value.

  [EILSEQ]
      The s parameter points to an invalid multibyte character.

SEE ALSO
  Functions: btowc(3), mblen(3), wctomb(3), mbstowcs(3), wcstombs(3),
  wctob(3)

  Files: locale(4)

Index for Section 3

Alphabetical listing for M

Top of page