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

Guardian Native C Library Calls (t - z) wcstombs(3)
NAME
wcstombs - Converts a wide character string into a multibyte 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 wcstombs (
char *s,
const wchar_t *pwcs,
size_t n);
PARAMETERS
s Points to the location where the converted multibyte-character string is stored.
pwcs Points to the wide-character string to be converted.
n Specifies the number of bytes to be converted.
DESCRIPTION
The wcstombs() function converts a wide-character string into a multibyte-character string and
stores the coverted string in a location pointed to by the s parameter. The wcstombs() function
only stores 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.
• It has encountered a null wide character in the pwcs wide-character string and has writ-
ten a corresponding null byte in s.
• It cannot store the next converted wide character because there there is not enough room
in s, that is, it would have to store more than n bytes in the s parameter to store the char-
acter.
• It has already stored n bytes in the s parameter.
• An invalid wide character code is encountered in the pwcs wide-character string.
If the wcstombs() function stores exactly n bytes in the s parameter, it does not store a terminat-
ing null byte.
To ensure that there is enough room in the s parameter to fit the converted string, you can allocate
enough memory to store the maximum multi-byte 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 the length of the pwcs wide-character string multiplied by the value of MB_CUR_MAX in
the current locale. The wcslen() function returns the length of a wide-character string.
527192-005 Hewlett-Packard Company 7−77