multibyte(3C)multibyte(3C)NAMEmblen(), mbtowc(), mbstowcs(), wctomb(), wcstombs() - multibyte charac‐
ters and strings conversions
SYNOPSISDESCRIPTION
A multibyte character is composed of one or more bytes that represent a
"whole" character in a character encoding. A wide character (type of
is composed of a fixed number of bytes whose code value can represent
any character in a character encoding.
Determine the number of bytes in the multibyte character pointed to by
s. Equivalent to:
If s is a null pointer, mblen returns a nonzero or zero
value, depending on whether the multibyte character encod‐
ings do or do not have state-dependent encodings, respec‐
tively. Since no character encodings currently supported
by HP-UX are state-dependent, zero is always returned in
this case. However, for maximum portability to other sys‐
tems, application programs should not depend on this.
If s is not a null pointer, mblen returns the number of
bytes in the multibyte character if the next n or fewer
bytes form a valid multibyte character, or return -1 if
they do not form a valid multibyte character. If s points
to the null character, mblen returns 0.
Determine the number of bytes in the multibyte character pointed to by
s, determine the code for the value of type corresponding
to that multibyte character, then store the code in the
object pointed to by pwc. The value of the code corre‐
sponding to the null character is zero. At most n charac‐
ters are examined, starting at the character pointed to by
s.
If s is a null pointer, returns a non-zero or zero value,
depending on whether the multibyte character encodings do
or do not have state-dependent encodings, respectively.
Since no character encodings currently supported by HP-UX
are state-dependent, zero is always returned in this case.
However, for maximum portability to other systems, applica‐
tion programs should not depend on this.
If s is not a null pointer, returns the number of bytes in
the converted multibyte character if the next n or fewer
bytes form a valid multibyte character, or -1 if they do
not form a valid multibyte character. If s points to the
null character, returns 0. The value returned is never
greater than n or the value of the macro.
Determine the number of bytes needed to represent
the multibyte character corresponding to the code whose
value is wchar and store the multibyte character represen‐
tation in the array object pointed to by s. At most char‐
acters are stored.
If s is a null pointer, returns a nonzero or zero value,
depending on whether the multibyte character encodings do
or do not have state-dependent encodings, respectively.
Since no character encodings currently supported by HP-UX
are state-dependent, zero is always returned in this case.
However, for maximum portability to other systems, applica‐
tion programs should not depend on this.
If s is not a null pointer, returns the number of bytes in
the multibyte character corresponding to the value of
wchar, or -1 if the value of wchar does not correspond to a
valid multibyte character. The value returned is never
greater than the value of the macro.
Convert a sequence of multibyte characters
from the array pointed to by s into a sequence of corre‐
sponding codes and store these codes into the array pointed
to by pwcs, stopping after either n codes or a code with
value zero (a converted null character) is stored. Each
multibyte character is converted as if by a call to No more
than n elements are modified in the array pointed to by
pwcs.
If an invalid multibyte character is encountered, returns
(size_t)−1. Otherwise, returns the number of array ele‐
ments modified, not including a terminating zero code, if
any. The array is not null- or zero-terminated if the
value returned is n. If pwcs is a null pointer, returns
the number of elements required for the wide-character-code
array.
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 No
more than n bytes are modified in the array pointed to by
s.
If a code is encountered that does not correspond to a
valid multibyte character, returns (size_t)−1. Otherwise,
returns the number of bytes modified, not including a ter‐
minating null character, if any. The array is not null- or
zero-terminated if the value returned is n. If s is a null
pointer, returns the number of bytes required for the char‐
acter array.
EXTERNAL INFLUENCES
Locale
The category determines the behavior of the multibyte character and
string functions.
ERRORS
and may fail and 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 charac‐
ters (type of are specific to the effective locale specified by the
environment variable. These values may not be compatible 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 not be used, and that wide
character code values not be stored in files or devices because future
standards may dictate changes in the code value assignments of the wide
characters. However, wide character 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.
SEE ALSOsetlocale(3C), wctype(3C), thread_safety(5), glossary(9).
STANDARDS CONFORMANCEmultibyte(3C)