Index for Section 3

Alphabetical listing for W

Bottom of page

wctomb(3)
NAME
  wctomb, wcrtomb - Convert a wide character into a multibyte character

SYNOPSIS
  #include <stdlib.h>

  int wctomb(
	  char *s,
	  wchar_t wc );

  #include <wchar.h>

  size_t wcrtomb(
	  char *s,
	  wchar_t wc,
	  mbstate_t *ps );

LIBRARY
  Standard C Library (libc)

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

  wctomb(), wcrtomb(): XSH5.0

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

PARAMETERS
  *s  Points to the location where the conversion is stored.

  wc  Specifies the wide character to be converted.

  *ps Points to a mbstate_t structure that contains the conversion state of
      the data in s.

DESCRIPTION
  The wctomb() function converts a wide character into a multibyte character
  and stores the result in s. The wctomb() function stores no more than
  MB_CUR_MAX bytes in s and returns the number of bytes stored.

  The behavior of the wctomb() function is affected by the LC_CTYPE category
  of the current locale. In environments with shift-state dependent encoding,
  calls to the wctomb() function with the wchar parameter set to 0 (zero) put
  the function in its initial shift state. Subsequent calls with the wc
  parameter set to nonzero values alter the state of the function as
  necessary. Changing the LC_CTYPE category of the locale causes the shift
  state of the function to be unreliable.

  The implementation behaves as though no other function calls the wctomb()
  function.

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

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

  If wc is a null wide character, wcrtomb() stores a null byte in s. If the
  current locale defines shift-state encoding, the function also precedes the
  null byte with the shift sequence needed to restore the initial shift
  state; in this case, completion of the call sets the conversion state to
  the initial conversion state.

RESTRICTIONS
  The wcrtomb() and other restartable versions of conversion routines are
  functional only when used with locales that support shift-state encoding.
  Currently, the operating system does not provide any locales that use
  shift-state encoding. Therefore, the wcrtomb() function has the same run-
  time behavior as the wctomb() function and neither function returns values
  for state-dependent conditions.

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

    ·  A positive value indicating the number of bytes in the multibyte
       character, if the wc parameter corresponds to a valid multibyte
       character

    ·  -1, if the wc parameter does not correspond to a valid multibyte
       character.

       [Tru64 UNIX]  In this case, the function also sets errno to indicate
       the error.

  If *s is not a null pointer, the wcrtomb() function returns one of the
  following values:

    ·  A positive value indicating the number of bytes (including shift
       sequences) stored in s, if wc can be converted to a valid multibyte
       character

    ·  (size_t)-1, if wc is not a valid wide character. In this case, the
       conversion state is undefined and the function sets errno to indicate
       the error.

  If *s is a null pointer, both the wctomb() and wcrtomb() functions return
  one of the following values, depending on whether the current locale uses
  state-dependent encoding:

    ·  0 (zero), if encoding is not state dependent

    ·  A nonzero value, if encoding is state dependent

  In no case do the wctomb() or wcrtomb() functions return a value greater
  than the value of the MB_CUR_MAX variable.

ERRORS
  If the following condition occurs, the wctomb() and wcrtomb() functions set
  errno to the corresponding value:

  [EILSEQ]
      [Tru64 UNIX]  The wc parameter contains an invalid wide-character
      value.

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

  Files: locale(4)

Index for Section 3

Alphabetical listing for W

Top of page