mbrtowc man page on MirBSD

Man page or keyword search:  
man Server   6113 pages
apropos Keyword Search (all sections)
Output format
MirBSD logo
[printable version]

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

NAME
     mbrtowc - converts a multibyte character to a wide character (restart-
     able)

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 in 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 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 null
     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 conver-
     sion suspended.

     The behaviour of the 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 charac-
		   ter has taken place and the conversion state may be affect-
		   ed, but the resultant 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 libc never change the inter-
		   nal 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 null character.

     positive	   If s points to a valid character, mbrtowc() returns the
		   number of bytes in the character.
     (size_t)-2	   s points to the byte sequence which possibly contains part
		   of a valid multibyte character, but which is incomplete.
		   When n is at least MB_CUR_MAX only occurs 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
     The mbrtowc() may causes 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), optu8to16(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").

MirOS BSD #10-current	      November 22, 2008				     1
[top]

List of man pages available for MirBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net