Unix/Linux Go Back    


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

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


MBSRTOWCS(3)			   BSD Library Functions Manual 		     MBSRTOWCS(3)

NAME
     mbsrtowcs -- converts a multibyte character string to a wide-character string (restartable)

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <wchar.h>

     size_t
     mbsrtowcs(wchar_t * restrict pwcs, const char ** restrict s, size_t n,
	 mbstate_t * restrict ps);

DESCRIPTION
     The mbsrtowcs() converts the multibyte character string indirectly pointed to by s to the
     corresponding wide-character string, and stores it in the array pointed to by pwcs.  The
     conversion stops due to the following reasons:

     o	 The conversion reaches a nul byte.  In this case, the nul byte is also converted.

     o	 The mbsrtowcs() has already stored n wide characters.

     o	 The conversion encounters an invalid character.

     Each character will be converted as if mbrtowc(3) is continuously called.

     After conversion, if pwcs is not a null pointer, the pointer object pointed to by s is a
     null pointer (if the conversion is stopped due to reaching a nul byte) or the first byte of
     the character just after the last character converted.

     If pwcs is not a null pointer and the conversion is stopped due to reaching a nul byte, the
     mbsrtowcs() places the state object pointed to by ps to an initial state after the conver-
     sion has taken place.

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

     These are the special cases:

     s == NULL || *s == NULL
		   Undefined (may cause the program to crash).

     pwcs == NULL  The conversion has taken place, but the resulting wide-character string was
		   discarded.  In this case, the pointer object pointed to by s is not modified
		   and n is ignored.

     ps == NULL    The mbsrtowcs() 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 mbsrtowcs(), which is initialized at startup time of the
		   program.

RETURN VALUES
     mbsrtowcs() returns:

     0 or positive
		   The value returned is the number of elements stored in the array pointed to by
		   pwcs, except for a terminating nul wide character (if any).	If pwcs is not
		   NULL and the value returned is equal to n, the wide-character string pointed
		   to by pwcs is not nul-terminated.  If pwcs is a null pointer, the value
		   returned is the number of elements to contain the whole string converted,
		   except for a terminating nul wide character.

     (size_t)-1    The array indirectly pointed to by s contains a byte sequence forming invalid
		   character.  In this case, mbsrtowcs() sets errno to indicate the error.

ERRORS
     mbsrtowcs() may cause an error in the following case:

     [EILSEQ]		The pointer pointed to by s points to an invalid or incomplete multibyte
			character.

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

SEE ALSO
     mbrtowc(3), mbstowcs(3), setlocale(3)

STANDARDS
     The mbsrtowcs() 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 01:55 PM.