|
» |
|
|
|
NAMEmblen(), mbtowc(), mbstowcs(), wctomb(), wcstombs() — multibyte characters and strings conversions SYNOPSIS#include <stdlib.h> int mblen(const char *s, size_t n); int mbtowc(wchar_t *__restrict pwc, const char *__restrict s, size_t n); int wctomb(char *s, wchar_t wchar); size_t mbstowcs(wchar_t *__restrict pwcs, const char *__restrict s, size_t n); size_t wcstombs(char *__restrict s, const wchar_t *__restrict pwcs, size_t n); DESCRIPTIONA multibyte character is composed of one or more bytes that
represent a "whole" character in a character encoding.
A wide character (type of
wchar_t)
is composed of a fixed number of bytes whose code value
can represent any character in a character encoding.
- mblen()
Determine the number of bytes in the multibyte character pointed to by
s.
Equivalent to: mbtowc((wchar_t *)0, s, n); If
s
is a null pointer,
mblen
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,
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. - mbtowc()
Determine the number of bytes in the multibyte character pointed to by
s,
determine the code for the value of type
wchar_t
corresponding to that multibyte character,
then store the code in the object pointed to by
pwc.
The value of the code corresponding to the null character is zero.
At most
n
characters are examined, starting at the character pointed to by
s. If
s
is a null pointer,
mbtowc()
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,
application programs should not depend on this. If
s
is not a null pointer,
mbtowc()
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,
mbtowc()
returns 0.
The value returned is never greater than
n
or the value of the
MB_CUR_MAX
macro. - wctomb()
Determine the number of bytes needed to represent
the multibyte character corresponding to the code whose value is
wchar
and store the multibyte character representation
in the array object pointed to by
s.
At most
MB_CUR_MAX
characters are stored. If
s
is a null pointer,
wctomb()
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,
application programs should not depend on this. If
s
is not a null pointer,
wctomb()
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
MB_CUR_MAX
macro. - mbstowcs()
Convert a sequence of multibyte characters
from the array pointed to by
s
into a sequence of corresponding 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
mbtowc().
No more than
n
elements are modified in the array pointed to by
pwcs. If an invalid multibyte character is encountered,
mbstowcs()
returns (size_t)-1.
Otherwise,
mbstowcs()
returns the number of array elements 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,
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 modified 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 modified,
not including a terminating null character, if any.
The array is not null- or zero-terminated if the value returned is
n.
If
s
is a null pointer,
wcstombs()
returns the number of bytes required for the character array.
EXTERNAL INFLUENCESLocaleThe
LC_CTYPE
category determines the behavior of the multibyte character
and string functions. ERRORSmblen(),
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.
WARNINGSWith the exception of
ASCII
characters, the code values of wide characters (type of
wchar_t)
are specific to the effective locale specified by the
LC_CTYPE
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
C Reference Manual)
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. AUTHORThe multibyte functions in this entry were developed by OSF and HP. STANDARDS CONFORMANCEmblen(): AES, SVID3, XPG4, ANSI C mbstowcs(): AES, SVID3, XPG4, ANSI C mbtowc(): AES, SVID3, XPG4, ANSI C wcstombs(): AES, SVID3, XPG4, ANSI C wctomb(): AES, SVID3, XPG4, ANSI C
|