HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

m
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 *__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);
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 multi-
byte 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 pro-
grams 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
HP-UX 11i Version 3: February 2007 − 1 − Hewlett-Packard Company 801