HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

609

610

611

612

613

614

615

616

617

618

multibyte(3C) multibyte(3C)

character is converted as if by a call to

mbtowc(). No more than n elements are modiﬁed in

the array pointed to by pwcs.

If an invalid multibyte character is encountered,

mbstowcs()

returns (size_t)− 1. Other-

wise,

mbstowcs() returns the number of array elements modiﬁed, not including a ter-

minating zero code, if any. The array is not null- or zero-terminated if the value returned is n.

If pwcs is a null pointer,

mbstowcs() returns the number of elements required for the

wide-character-code array.

wcstombs()

Convert a sequence of codes corresponding to multibyte characters from the array pointed to

by pwcs into a sequence of multibyte characters and store them into the array pointed to by s,

stopping if a multibyte character exceeds the limit of n total bytes or if a null character is

stored. Each code is converted as if by a call to

wctomb(). No more than n bytes are

modiﬁed in the array pointed to by s.

If a code is encountered that does not correspond to a valid multibyte character,

wcstombs() returns (size_t)− 1. Otherwise, wcstombs() returns the number of bytes

modiﬁed, not including a terminating null character, if any. The array is not null- or zero-

terminated if the value returned is n.Ifs is a null pointer,

wcstombs() returns the

number of bytes required for the character array.

EXTERNAL INFLUENCES

Locale

The

LC_CTYPE category determines the behavior of the multibyte character and string functions.

ERRORS

mblen(), mbstowcs(), mbtowc(), wcstombs() and wctomb() may fail and errno is set if the

following condition is encountered:

[EILSEQ] An invalid multibyte sequence or wide character code was found.

WARNINGS

With the exception of ASCII characters, the code values of wide characters (type of wchar_t) are speciﬁc

to the effective locale speciﬁed by the

LC_CTYPE environment variable. These values may not be compa-

tible with values obtained by specifying other locales that are supported now, or which may be supported in

the future. It is recommended that wide character constants and wide string literals (see the C Reference

Manual) not be used, and that wide character code values not be stored in ﬁles or devices because future

standards may dictate changes in the code value assignments of the wide characters. However, wide char-

acter constants and wide string literals corresponding to the characters of the

ASCII code set can be safely

used since their values are guaranteed to be the same as their

ASCII code set values.

AUTHOR

The multibyte functions in this entry were developed by OSF and HP.