Manual Pages for UNIX Operating System command usage for man mbrtowc

Standard C Library Functions                          mbrtowc(3C)



NAME
     mbrtowc - convert a character to a wide-character code (res-
     tartable)

SYNOPSIS
     #include 

     size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s, size_t n,
          mbstate_t *restrict ps);


DESCRIPTION
     If s is a null pointer, the mbrtowc() function is equivalent
     to the call:

       mbrtowc(NULL, ``'', 1, ps)



     In this case, the values of the  arguments  pwc  and  n  are
     ignored.


     If s is not a null pointer, the mbrtowc() function  inspects
     at  most  n  bytes beginning at the byte pointed to by  s to
     determine the number of bytes needed to  complete  the  next
     character  (including any shift sequences).  If the function
     determines that the next character is completed,  it  deter-
     mines  the  value  of  the  corresponding wide-character and
     then, if pwc is not a null pointer, stores that value in the
     object  pointed  to  by  pwc.  If  the  corresponding  wide-
     character is the null wide-character,  the  resulting  state
     described is the initial conversion state.


     If ps is a null pointer, the mbrtowc() function uses its own
     internal  mbstate_t  object, which is initialized at program
     startup to the initial conversion  state.    Otherwise,  the
     mbstate_t  object  pointed  to  by  ps is used to completely
     describe the current  conversion  state  of  the  associated
     character  sequence.  Solaris  will behave as if no function
     defined in the Solaris Reference Manual calls mbrtowc().


     The behavior of this function is affected  by  the  LC_CTYPE
     category of the current locale.  See environ(5).

RETURN VALUES
     The mbrtowc() function returns the first  of  the  following
     that applies:





SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                          mbrtowc(3C)



     0                If the next n or fewer bytes  complete  the
                      character  that  corresponds  to  the  null
                      wide-character (which is the value stored).


     positive         If the next n or  fewer  bytes  complete  a
                      valid   character   (which   is  the  value
                      stored); the value returned is  the  number
                      of bytes that complete the character.


     (size_t)-2       If the next n bytes contribute to an incom-
                      plete but potentially valid  character, and
                      all n bytes have been processed  (no  value
                      is stored).   When n has at least the value
                      of the MB_CUR_MAX macro, this case can only
                      occur  if  s points at a sequence of redun-
                      dant shift sequences  (for  implementations
                      with state-dependent encodings).


     (size_t)-1       If an encoding error occurs, in which  case
                      the next n or fewer bytes do not contribute
                      to a  complete  and  valid   character  (no
                      value  is stored).  In this case, EILSEQ is
                      stored in errno and the conversion state is
                      undefined.


ERRORS
     The mbrtowc() function may fail if:

     EINVAL    The ps argument points to an object that  contains
               an invalid conversion state.


     EILSEQ    Invalid character sequence is detected.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:













SunOS 5.11           Last change: 1 Nov 2003                    2






Standard C Library Functions                          mbrtowc(3C)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below             |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     mbsinit(3C), setlocale(3C), attributes(5), environ(5), stan-
     dards(5)

NOTES
     If ps is not a null pointer, mbrtowc()  uses  the  mbstate_t
     object  pointed to by ps and the function can be used safely
     in multithreaded applications, as long as  setlocale(3C)  is
     not  being  called  to  change  the  locale. If ps is a null
     pointer, mbrtowc() uses its internal  mbstate_t  object  and
     the function is Unsafe in multithreaded applications.

































SunOS 5.11           Last change: 1 Nov 2003                    3