Index for Section 3

Alphabetical listing for W

Bottom of page

wcstombs(3)
NAME
  wcstombs, wcsrtombs - Convert a wide-character string into a multibyte-
  character string

SYNOPSIS
  #include <stdlib.h>

  size_t wcstombs(
	  char *s,
	  const wchar_t *pwcs,
	  size_t n );

  #include <wchar.h>

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

LIBRARY
  Standard C Library (libc)

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

  wcstombs(): ISO C, XPG4

  wcsrtombs(): ISO C

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

PARAMETERS
  *s  Points to the location where the converted multibyte-character string
      is stored.

  *pwcs or **pwcs
      Points or indirectly points to the address of the wide-character string
      to be converted.

  n   Specifies the maximum number of bytes to be stored in the output
      variable (s).

  *ps Points to an mbstate_t structure containing the conversion state of the
      data in pwcs.

DESCRIPTION
  The wcstombs() function converts a wide-character string into a multibyte-
  character string and stores the result in a location pointed to by the s
  parameter. The wcstombs() function stores only the number of bytes
  specified by the n parameter as the output string. When copying between
  objects that overlap, the behavior of wcstombs() is undefined.

  The behavior of the wcstombs() function is affected by the LC_CTYPE
  category of the current locale. In environments that use shift-state-
  dependent encoding, the array pointed to by s begins in its initial shift
  state.

  The wcstombs() function converts each character in the pwcs wide-character
  string and stores the converted character in the s string. The wcstombs()
  function stops storing characters in the output array under the following
  conditions:

    ·  The function has encountered a null wide character in the pwcs wide-
       character string and has written a corresponding null byte in s.

    ·  The function cannot store the next converted wide character because
       there is not enough room in s; that is, the function would have to
       store more than n bytes in the s parameter to store the character.

    ·  The function has already stored n bytes in the s parameter.

    ·  The function has encountered an invalid wide-character code in the
       pwcs wide-character string.

  If the wcstombs() function stores exactly n bytes in the s parameter, the
  function does not store a terminating null byte.

  To ensure that there is enough room in the s parameter to fit the converted
  string, the application should allocate enough memory to store the maximum
  multibyte-character string based on the number of wide characters in the
  wide-character string. Allocate the number of bytes (and pass the value in
  the n parameter) equal to the length of the pwcs wide-character string (as
  determined by the wcslen() or wcsrlen() function) multiplied by the value
  of MB_CUR_MAX in the current locale.	A prior call to wcstombs() or
  wcsrtombs() can perform this calculation for the application. For example,
  on the first call to wcstombs() or wcsrtombs(), the application can pass s
  as a null pointer to obtain the number of bytes (not including the
  terminating null byte) required for s. The application then uses this
  return value as the value for n in the call to wcstombs() or wcsrtombs()
  that performs the conversion.

  The wcsrtombs() function is a restartable version of wcstombs().
  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. Results are undefined
  when an application uses restartable and nonrestartable conversion
  functions with the same source and destination variables. For example, an
  application would use wcsrlen() rather than wcslen() to determine the
  length of pwcs if that variable were to be processed with wcsrtombs()
  rather than wcstombs().

RESTRICTIONS
  The wcsrtombs() and other restartable versions of conversion routines are
  functional only when used with locales that support shift state encoding.
  Currently, the Tru64 UNIX product does not provide any locales that use
  shift state encoding, so the wcstombs() and wcsrtombs() functions do not
  differ in terms of run-time behavior.

RETURN VALUES
  If the wcstombs() and wcsrtombs() functions do not encounter an invalid
  wide-character code, they return the number of bytes stored, not including
  the terminating null byte. When these functions encounter a wide-character
  code that does not correspond to a valid multibyte character, they return a
  value of -1 cast to size_t and set errno to indicate the error.

  If the wcstombs() and wcsrtombs() cannot store all of the converted
  characters in the output array, the functions stop before storing a
  character that would overflow the output array and return the number of
  bytes stored in the array. When the return value is n, the output array is
  not null terminated.

  If these functions are called with a null pointer value for s, they return
  the number of bytes required for the output character array.

ERRORS
  If any of the following conditions occur, the wcstombs() and wcsrtombs()
  functions set errno to the corresponding value:

  [EILSEQ]
      The array pointed to by the pwcs parameter contains an entry that does
      not correspond to a valid multibyte character.

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

Index for Section 3

Alphabetical listing for W

Top of page