mbstowcs(3) - NetBSD Manual Pages

Command: Section: Arch: Collection:  
MBSTOWCS(3)             NetBSD Library Functions Manual            MBSTOWCS(3)


NAME
mbstowcs -- converts a multibyte character string to a wide-character string
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h> size_t mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);
DESCRIPTION
mbstowcs() converts a nul-terminated multibyte character string pointed to by s to the corresponding wide-character string and stores it in the array pointed to by pwcs. This function may modify the first at most n elements of the array pointed to by pwcs. Each character will be con- verted as if mbtowc(3) is continuously called, except the internal state of mbtowc(3) will not be affected. For state-dependent encoding, mbstowcs() implies the multibyte character string pointed to by s always begins with an initial state. These are the special cases: pwcs == NULL mbstowcs() returns the number of elements to store the whole wide-character string corresponding to the multibyte character string pointed to by s. In this case, n is ignored. s == NULL Undefined (may cause the program to crash).
RETURN VALUES
mbstowcs() returns: 0 or positive Number of elements stored in the array pointed to by pwcs. There are no cases that the value returned is greater than n (unless pwcs is a null pointer) or the value of the MB_CUR_MAX macro. If the return value is equal to n, the string pointed to by pwcs will not be nul-terminated. (size_t)-1 s points to a string containing an invalid or incomplete multibyte character. The mbstowcs() also sets errno to indicate the error.
ERRORS
mbstowcs() may cause an error in the following case: [EILSEQ] s points to a string containing an invalid or incom- plete multibyte character.
SEE ALSO
mbtowc(3), setlocale(3), wcstombs(3)
STANDARDS
The mbstowcs() function conforms to ANSI X3.159-1989 (``ANSI C89''). The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99''). NetBSD 9.99 March 16, 2011 NetBSD 9.99
Powered by man-cgi (2021-06-01). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.