unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MBLEN(3)                   Library Functions Manual                   MBLEN(3)



NAME
       mblen,  mbstowcs,  mbtowc,  wcstombs, wctomb - multibyte character han-
       dling

SYNOPSIS
       #include <&lt;stdlib.h>&gt;

       int mblen(s, n)
       char *s;
       size_t n;

       size_t mbstowcs(s, pwcs, n)
       char *s;
       wchar_t *pwcs;
       size_t n;

       int mbtowc(pwc, s, n)
       wchar_t *pwc;
       char *s;
       size_t n;

       int wcstombs(s, pwcs, n)
       char *s;
       wchar_t *pwcs;
       size_t n;

       int wctomb(s, wchar)
       char *s;
       wchar_t wcar;

DESCRIPTION
       The behavior of these functions is affected by the LC_CTYPE category of
       the  program's locale.  For a stat-dependent encoding, each function is
       placed into its initial state by a call for which its character pointer
       argument,  s, is a NULL pointer.  Subsequent calls with s as other than
       a NULL pointer cause the internal stste of the function to  be  altered
       as necessary.  A call with a s as a NULL pointer causes these functions
       to return a nonzero value if encodings have state dependency, and  zero
       otherwise.   After the LC_CTYPE category is changed, the shift state of
       these functions is indeterminate.

       If s is not a NULL pointer, these functions work as follows:

       mblen()
              Determines the number of bytes comprising the multibyte  charac-
              ter pointed to by s.

       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 no more than n codes
              into the array pointed to by pwcs.  No multibyte characters that
              follow  a  null  character  (which is converted into a code with
              value zero) will be examined or converted.  Each multibyte char-
              acter  is converted as if by a call to mbtowc(), except that the
              shift state of mbtowc() is not affected.

              No more than n elements will be modified in the array pointed to
              by  pwcs.   If copying takes place between objects that overlap,
              the behavior is undefined.

       mbtowc()
              Determines the number of bytes that comprise the multibyte char-
              acter  pointed  to  by s.  mbtowc() then determines the code for
              value of type wchar_t that corresponds to that multibyte charac-
              ter.  The value of the code corresponding to the null caharacter
              is zero.  If the multibyte character is valid and pwc is  not  a
              null  pointer, mbtowc() stores the code in the object pointed to
              by pwc.  At most n bytes of the array pointed to by  s  will  be
              examined.

       wcstowcs()
              Converts  a sequence of codes that correspond to multibyte char-
              acters from the array pointed to by  pwcs  into  a  sequence  of
              multibyte  characters that begins in the initial shift state and
              stores these multibyte characters into the array pointed  to  by
              s, stopping if a multibyte character would exceed the limit of n
              total bytes or if a null character is stored.  Each code is con-
              verted  as if by a call to wctomb(), except that the shift state
              of wctomb() is not affected.

       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).   wctomb()  stores  the
              multibyte  character  representation in the array object pointed
              to by s (if s is not a null pointer).  At most, MB_CUR_MAX char-
              acters  are  stored.  If the value of wchar is zero, wctomb() is
              left in the initial shift state.

RETURN VALUES
       If s is a null  pointer,  mblen(),  mbtowc(),  and  wctomb()  return  a
       nonzero  or zero value, if multibyte character encodings, respectively,
       do or do not have state dependent encodings.

       If s is not a null pointer, mblen() and mbtowc() either return 0 (if  s
       points  to the null character), or return the number of bytes that com-
       prise the converted 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).

       In no case will the value returned by mbtowc() be greater than n or the
       value  of  the  MB_CUR_MAX macro.  If s is not a null pointer, wctomb()
       returns -1 (if the value does not correspond to a valid multibyte char-
       acter),  or  returns  the  number  of bytes that comprise the multibyte
       character corresponding to wchar.

       If an  invalid  multibyte  character  is  encountered,  mbstowcs()  and
       wcstombs()  return  (size_t)  -1.  Otherwise, they return the number of
       bytes modified, not including a terminating null character, if any.

NOTE
       When an application program using these routines is statically  linked,
       user  defined  multibyte character handling routines in a user provided
       shared library will not be used.




                                  6 June 1991                         MBLEN(3)