Guardian Native C Library Calls Reference Manual (G06.28+, H06.04+)

Guardian Native C Library Calls (j - m) mbstowcs(3)
NAME
mbstowcs - Converts a multibyte character string to a wide character string
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL
G-series native OSS processes: /G/system/sysnn/zcrtlsrl
H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
H-series OSS processes: /G/system/zdllnnn/zcrtldll
SYNOPSIS
#include <stdlib.h>
size_t mbstowcs (
wchar_t *pwcs,
const char *s,
size_t n);
PARAMETERS
pwcs Points to the array where the result of the conversion is stored.
s Points to the multibyte character string to be converted.
n Specifies the number of wide characters in the destination array.
DESCRIPTION
The mbstowcs() function converts a multibyte character string into a wide character string,
which is stored at a specified location. The mbstowcs() function does not convert characters
occurring after a null byte in the input string, which is converted to a value of 0 (zero). When
operating on overlapping strings, the behavior of this function is undefined.
NOTES
Behavior of the mbstowcs() 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 the s
parameter begins in the initial shift state.
RETURN VALUES
When mbstowcs() encounters an invalid multibyte character during conversion, it returns a
value of -1 cast to size_t and sets errno to indicate the error. Otherwise, mbstowcs() returns the
number of wide characters stored in the output array, not including a terminating null wide char-
acter. (When the return value is n, the output array is not null-terminated.)
ERRORS
If the following condition occurs, the mbstowcs() function sets errno to the corresponding
value.
[EILSEQ] The s parameter points to a string containing an invalid multibyte character.
RELATED INFORMATION
Functions: mblen(3), mbtowc(3), wctomb(3), wcstombs(3).
527192-005 Hewlett-Packard Company 4−45