Museum

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);

     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.

     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.  If the value of wchar is zero, wctomb is left in the initial
     shift state.

     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.

     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.

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.

NOTES
     Domain/OS SysV supports only the latin-1 character set.

     Parts of this discussion are adapted from ANS X3.159-1989.