Unix/Linux Go Back    


NetBSD 6.1.5 - man page for mbrtowc (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 initialized 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
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:23 PM.