mbrtowc(3) [netbsd man page]

MBRTOWC(3)						   BSD Library Functions Manual 						MBRTOWC(3)

NAME

     mbrtowc -- converts a multibyte character to a wide character (restartable)

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <wchar.h>

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

DESCRIPTION

     The mbrtowc() usually converts the multibyte character pointed to by s to a wide character, and stores the wide character to the wchar_t
     object pointed to by pwc if pwc is non-NULL and s points to a valid character.  The conversion happens in accordance with, and changes the
     conversion state described in the mbstate_t object pointed to by ps.  This function may examine at most n bytes of the array beginning from
     s.

     If s points to a valid character and the character corresponds to a nul wide character, then the mbrtowc() places the mbstate_t object
     pointed to by ps to an initial conversion state.

     Unlike mbtowc(3), the mbrtowc() may accept the byte sequence pointed to by s not forming a complete multibyte character but which may be part
     of a valid character.  In this case, this function will accept all such bytes and save them into the conversion state object pointed to by
     ps.  They will be used at subsequent calls of this function to restart the conversion suspended.

     The behaviour of mbrtowc() is affected by the LC_CTYPE category of the current locale.

     These are the special cases:

     s == NULL	   mbrtowc() sets the conversion state object pointed to by ps to an initial state and always returns 0.  Unlike mbtowc(3), the
		   value returned does not indicate whether the current encoding of the locale is state-dependent.

		   In this case, mbrtowc() ignores pwc and n, and is equivalent to the following call:

			 mbrtowc(NULL, "", 1, ps);

     pwc == NULL   The conversion from a multibyte character to a wide character has taken place and the conversion state may be affected, but the
		   resulting wide character is discarded.

     ps == NULL    mbrtowc() uses its own internal state object to keep the conversion state, instead of ps mentioned in this manual page.

		   Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of mbrtowc(), which is initial-
		   ized at startup time of the program.

RETURN VALUES

     In the usual cases, mbrtowc() returns:

     0		   The next bytes pointed to by s form a nul character.

     positive	   If s points to a valid character, mbrtowc() returns the number of bytes in the character.

     (size_t)-2    s points to a byte sequence which possibly contains part of a valid multibyte character, but which is incomplete.  When n is at
		   least MB_CUR_MAX, this case can only occur if the array pointed to by s contains a redundant shift sequence.

     (size_t)-1    s points to an illegal byte sequence which does not form a valid multibyte character.  In this case, mbrtowc() sets errno to
		   indicate the error.

ERRORS

     mbrtowc() may cause an error in the following case:

     [EILSEQ]		s points to an invalid or incomplete multibyte character.

     [EINVAL]		ps points to an invalid or uninitialized mbstate_t object.

SEE ALSO

     mbrlen(3), mbtowc(3), setlocale(3)

STANDARDS

     The mbrtowc() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, Amendment 1'').  The restrict qualifier is added at ISO/IEC 9899:1999
     (``ISO C99'').

BSD
								 February 4, 2002							       BSD

Check Out this Related Man Page

MBRTOWC(3)						     Linux Programmer's Manual							MBRTOWC(3)

NAME

       mbrtowc - convert a multibyte sequence to a wide character

SYNOPSIS

       #include <wchar.h>

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

DESCRIPTION

       The  main  case for this function is when s is not NULL and pwc is not NULL. In this case, the mbrtowc function inspects at most n bytes of
       the multibyte string starting at s, extracts the next complete multibyte character, converts it to a wide character and stores it at  *pwc.
       It  updates the shift state *ps. If the converted wide character is not L'', it returns the number of bytes that were consumed from s. If
       the converted wide character is L'', it resets the shift state *ps to the initial state and returns 0.

       If the n bytes starting at s do not contain a complete multibyte character, mbrtowc returns (size_t)(-2). This can  happen  even  if  n	>=
       MB_CUR_MAX, if the multibyte string contains redundant shift sequences.

       If  the	multibyte  string  starting  at  s  contains  an  invalid  multibyte  sequence before the next complete character, mbrtowc returns
       (size_t)(-1) and sets errno to EILSEQ. In this case, the effects on *ps are undefined.

       A different case is when s is not NULL but pwc is NULL. In this case the mbrtowc function behaves as above, excepts that it does not  store
       the converted wide character in memory.

       A  third  case  is  when  s  is NULL. In this case, pwc and n are ignored. If the conversion state represented by *ps denotes an incomplete
       multibyte character conversion, the mbrtowc function returns (size_t)(-1), sets errno to EILSEQ, and leaves *ps in an undefined state. Oth-
       erwise, the mbrtowc function puts *ps in the initial state and returns 0.

       In  all	of  the above cases, if ps is a NULL pointer, a static anonymous state only known to the mbrtowc function is used instead.  Other-
       wise, *ps must be a valid mbstate_t object.  An mbstate_t object a can be initialized to the initial state by zeroing it, for example using

	      memset(&a, 0, sizeof(a));

RETURN VALUE

       The mbrtowc function returns the number of bytes parsed from the multibyte sequence starting at s, if a non-L'' wide character was recog-
       nized.	It  returns 0, if a L'' wide character was recognized. It returns (size_t)(-1) and sets errno to EILSEQ, if an invalid multibyte
       sequence was encountered. It returns (size_t)(-2) if it couldn't parse a complete multibyte character, meaning that n should be increased.

CONFORMING TO

       ISO/ANSI C, UNIX98

SEE ALSO

       mbsrtowcs(3)

NOTES

       The behaviour of mbrtowc depends on the LC_CTYPE category of the current locale.

GNU
								    2001-11-22								MBRTOWC(3)

Linux and UNIX Man Pages

mbrtowc(3) [netbsd man page]

Check Out this Related Man Page