MirBSD manpage: mbsnrtowcs(3), mbsnrtowcsvis(3), mbsrtowcs(3)

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


     mbsrtowcs, mbsnrtowcs, mbsnrtowcsvis - convert a multibyte character
     string to a wide character


     #include <wchar.h>

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

     mbsnrtowcs(wchar_t *pwcs, const char **s, size_t max, size_t n,
             mbstate_t *ps);

     #include <mbfun.h>

     mbsnrtowcsvis(wchar_t *pwcs, const char **s, size_t max, size_t n,
             mbstate_t *ps);
     /* deprecated */


     mbsrtowcs() converts the multibyte character string indirectly pointed to
     by s to the corresponding wide character string, and stores it in the ar-
     ray pointed to by pwcs. mbsnrtowcs() behaves the same, but reads at most
     max octets from the string indirectly pointed to by s. mbsnrtowcsvis()
     behaves the same, but automatically converts input octets from 8-bit to
     UCS. The conversion stops due to the following reasons:

     •   The conversion reaches a null byte. In this case, the null byte is
         also converted.

     •   mbsrtowcs() or mbsnrtowcs() has already stored n wide characters.

     •   The conversion encounters an invalid character.

     •   The mbsnrtowcs() function has already devoured max octets.

     Each character is converted as if optu8to16(3) is continuously called.

     In the case of mbsnrtowcsvis(), each character is converted as if
     optu8to16vis(3) is continuously called; if the max argument is initially
     set to 0, the remaining state is drained.

     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 null 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 reach-
     ing a null byte, the mbsrtowcs() and mbsnrtowcs() functions place the
     state object pointed to by ps to an initial state after the conversion
     has taken place.

     The behaviour of the mbsrtowcs() and mbsnrtowcs() functions 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 resultant wide
                   character string was discarded. In this case, the pointer
                   object pointed to by s is not modified and n is ignored.

     ps == NULL    mbsrtowcs() uses its own internal state object to keep the
                   conversion state, instead of ps mentioned in this manual
                   page. mbsnrtowcs() has an own internal state which is dif-
                   ferent from the one of mbsrtowcs().

                   Calling any other functions in libc never change the inter-
                   nal state of mbsnrtowcs() or mbsrtowcs(), which is initial-
                   ised at startup time of the program.


     mbsrtowcs() and mbsnrtowcs() return:

     0 or positive
                   The value returned is the number of elements stored in the
                   array pointed to by pwcs, except for a terminating null
                   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 null terminated. If pwcs is a null
                   pointer, the value returned is the number of elements to
                   contain the whole string converted, except for a terminat-
                   ing null wide character.

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


     mbsrtowcs() and mbsnrtowcs() may cause an error in the following cases:

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

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


     mbrtowc(3), mbstowcs(3), optu8to16(3), optu8to16vis(3), setlocale(3)


     The mbsrtowcs() function conforms to ISO/IEC 9899/AMD1:1995 ("ISO C90,
     Amendment 1"). The mbsnrtowcs() function is a GNU extension.

     The mbsnrtowcsvis() function assumes codepage 1252 and maps holes into
     distinguishable codepoints. This extended function declares a macro with
     the same name that can be used to check for its presence.


     mbsnrtowcs() first appeared in MirBSD #10. mbsnrtowcsvis() first appeared
     in MirBSD #11.

MirBSD #10-current             December 7, 2021                              1

Generated on 2022-12-24 01:00:14 by $MirOS: src/scripts/roff2htm,v 1.113 2022/12/21 23:14:31 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2022 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.

Kontakt / Impressum & Datenschutzerklärung