HPUX multibyte[3c]
multibyte(3C) multibyte(3C)
NAME
mblen(), 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 *pwc, const char *s, size_t n);
int wctomb(char *s, wchar_t wchar);
size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);
size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);
DESCRIPTION
A 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.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
multibyte(3C) multibyte(3C)
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
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
multibyte(3C) multibyte(3C)
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 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 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.
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
multibyte(3C) multibyte(3C)
AUTHOR
The multibyte functions in this entry were developed by HP.
SEE ALSO
setlocale(3C), nl_tools_16(3C), wctype(3X).
STANDARDS CONFORMANCE
mblen(): AES, XPG4, ANSI C
mbstowcs(): AES, XPG4, ANSI C
mbtowc(): AES, XPG4, ANSI C
wcstombs(): AES, XPG4, ANSI C
wctomb(): AES, XPG4, ANSI C
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992