NAME
wcstombs —
converts a wide-character
string to a multibyte character string
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
size_t
wcstombs(
char *
restrict s,
const wchar_t *
restrict pwcs,
size_t
n);
DESCRIPTION
wcstombs() converts the nul-terminated wide-character string
pointed to by
pwcs to the corresponding multibyte
character string, and stores it in the array pointed to by
s. This function may modify the first at most
n bytes of the array pointed to by
s. Each character will be converted as if
wctomb(3) is continuously
called, except the internal state of
wctomb(3) will not be affected.
For state-dependent encoding, the
wcstombs() implies the
result multibyte character string pointed to by
s always
to begin with an initial state.
The behaviour of
wcstombs() is affected by the
LC_CTYPE
category of the current locale.
These are the special cases:
-
-
- s == NULL
- The wcstombs() returns the number of
bytes to store the whole multibyte character string corresponding to the
wide-character string pointed to by pwcs. In this
case, n is ignored.
-
-
- pwcs == NULL
- Undefined (may cause the program to crash).
RETURN VALUES
wcstombs() returns:
-
-
- 0 or positive
- Number of bytes stored in the array pointed to by
s. There are no cases that the value returned is
greater than n (unless s is a
null pointer). If the return value is equal to n,
the string pointed to by s will not be
nul-terminated.
-
-
- (size_t)-1
- pwcs points to a string containing an
invalid wide character. wcstombs() also sets
errno to indicate the error.
ERRORS
wcstombs() may cause an error in the following case:
-
-
- [
EILSEQ
]
- pwcs points to a string containing an
invalid wide character.
SEE ALSO
mbstowcs(3),
setlocale(3),
wctomb(3)
STANDARDS
The
wcstombs() function conforms to
ANSI
X3.159-1989 (“ANSI C89”). The restrict qualifier is
added at
ISO/IEC 9899:1999
(“ISO C99”).