WCTOMB(3C) SysV WCTOMB(3C)
NAME
mblen, mbtowc, wctomb, mbstowcs, wcstombs - convert multibyte characters
and strings to wide characters and strings and back
SYNOPSIS
#include <stdlib.h>
int mblen(s, n)
const char *s;
size_t n;
int mbtowc(pwc, s, n)
wchar_t *pwc;
const char *s;
size_t n;
int wctomb(s, wchar)
char *s;
wchar_t wchar;
size_t mbstowcs(pwcs, s, n)
wchar_t *pwcs;
const char *s;
size_t n;
size_t wcstombs(s, pwcs, n)
char *s;
const wchar_t *pwcs;
size_t n;
DESCRIPTION
mblen determines the number of bytes constituting the multibyte character
pointed to by s. Except that the shift state of mbtowc is not affected,
it is equivalent to
mbtowc((wchar_t *)0, s, n);
The behavior of the mblen function is affected by the LC_CTYPE category
of the current locale. In environments with shift-state dependent
encoding, calls to mblen with a null value for the s argument place the
function in the initial shift state. Subsequent calls with the s argument
set to nonnull values alter the state of the function as necessary.
Changing the LC_CTYPE category of the locale causes the shift state of
the function to be indeterminate.
mbtowc determines the number of bytes constituting the multibyte
character pointed to by s. If the code for the value of type wchar_t
corresponding to that multibyte character is valid and pwc is not null,
mbtowc stores the code in the object pointed to by pwc. n determines the
maximum number of bytes in the array pointed to by s that mbtowc
examines.
In environments with shift-state dependent encoding, calls to mbtowc with
the s argument set to null, places the function in its initial shift
state. Subsequent calls with the s argument set to nonnull values alter
the state of the function as necessary. Changing the LC_CTYPE category
of the locale causes the shift state of the function to be unreliable.
wctomb determines the number of bytes needed to represent the multibyte
character corresponding to the code whose value is wchar (including any
change in shift state). It stores the multibyte character representation
in the array pointed to by s. wctomb stores a maximum of MB_CUR_MAX
characters.
The behavior of the wctomb function is affected by the LC_CTYPE category
of the current locale. In environments with shift-state dependent
encoding, calls to the wctomb function with the wchar argument set to 0
(zero) put the function in its initial shift state. Subsequent calls with
the wchar argument set to nonzero values alter the state of the function
as necessary. Changing the LC_CTYPE category of the locale causes the
shift state of the function to be unreliable.
mbstowcs converts a sequence of multibyte characters that begins in the
initial shift state from the array pointed to by s into a sequence of
corresponding codes and stores not more than n codes into the array
pointed to by pwcs. Conversion proceeds as it would if mbtowc were
called, except that the shift state of mbtowc is not affected. If
copying takes place between objects that overlap, the behavior is
undefined. mbstowcs converts nulls into a code with the value zero. It
does not examine or convert multibyte characters following a null.
Behavior of the mbstowcs function is affected by the LC_CTYPE category of
the current locale. In environments that use shift-state dependent
encoding, the array pointed to by the s argument begins in the initial
shift state.
wcstombs converts a sequence of codes corresponding to multibyte
characters from the array pointed to by pwcs into a sequence of multibyte
characters that begins in the initial shift state and stores these into
the array pointed to by s. Conversion proceeds as it would if wctomb
were called, except that the shift state of wctomb is not affected. If
copying takes place between objects that overlap, the behavior is
undefined. wcstombs stops after storing n multibyte characters or if it
encounters a null.
The behavior of the wcstombs function is affected by the LC_CTYPE
category of the current locale. In environments that use shift-state
dependent encoding, the array pointed to by s begins in its initial shift
state.
DIAGNOSTICS
If s is null, mblen, mbtowc, and wctomb return zero if multibyte
character encodings do not have state-dependent encodings and nonzero if
they do. If s is not null and the next n or fewer bytes form a valid
multibyte character, or if the value of wchar corresponds to a valid
multibyte character, in the case of wctomb, mblen, mbtowc, and wctomb
return the number of bytes in the multibyte character. This value is
never greater than MB_CUR_MAX. If s is not null and the next n or fewer
bytes do not form a valid multibyte character, or if the value of wchar
does not correspond to a valid multibyte character, in the case of
wctomb, mblen, mbtowc, and wctomb return -1. If s points to a null,
mblen and mbtowc return zero.
mbstowcs and wcstombs return (size_t)-1 if they encounter an invalid
multibyte character (in the case of mbstowcs) or a code not corresponding
to a valid multibyte character (in the case of wcstombs). Otherwise,
mbstowcs returns the number of array elements modified and wcstombs
returns the number of bytes modified. A terminating null, if any, does
not count.
ERRORS
The mblen, mbtowc, wctomb, mbstowcs, and wcstombs functions fail if:
[EINVAL] The s argument points to an invalid multibyte character.
NOTES
Domain/OS SysV supports only the latin-1 character set.
Parts of this discussion are adapted from ANS X3.159-1989.