DragonFly On-Line Manual Pages

Search: Section:  

MBSRTOWCS(3)          DragonFly Library Functions Manual          MBSRTOWCS(3)


NAME

     mbsrtowcs, mbsrtowcs_l, mbsnrtowcs, mbsnrtowcs_l -- convert a character
     string to a wide-character string (restartable)


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <wchar.h>

     size_t
     mbsrtowcs(wchar_t * restrict dst, const char ** restrict src, size_t len,
         mbstate_t * restrict ps);

     size_t
     mbsnrtowcs(wchar_t * restrict dst, const char ** restrict src,
         size_t nms, size_t len, mbstate_t * restrict ps);

     #include <xlocale.h>

     size_t
     mbsrtowcs_l(wchar_t * restrict dst, const char ** restrict src,
         size_t len, mbstate_t * restrict ps, locale_t locale);

     size_t
     mbsnrtowcs_l(wchar_t * restrict dst, const char ** restrict src,
         size_t nms, size_t len, mbstate_t * restrict ps, locale_t locale);


DESCRIPTION

     The mbsrtowcs() and mbsrtowcs_l() functions convert a sequence of
     multibyte characters pointed to indirectly by src into a sequence of
     corresponding wide characters and store at most len of them in the
     wchar_t array pointed to by dst, until they encounter a terminating null
     character ('\0').

     If dst is NULL, no characters are stored.

     If dst is not NULL, the pointer pointed to by src is updated to point to
     the character after the one that conversion stopped at.  If conversion
     stops because a null character is encountered, *src is set to NULL.

     The mbstate_t argument, ps, is used to keep track of the shift state.  If
     it is NULL, mbsrtowcs() and mbsrtowcs_l() use an internal, static
     mbstate_t object, which is initialized to the initial conversion state at
     program startup.

     The mbsnrtowcs() and mbsnrtowcs_l() functions behave identically to
     mbsrtowcs() and mbsrtowcs_l(), except that conversion stops after reading
     at most nms bytes from the buffer pointed to by src.

     The mbsrtowcs_l() and mbsnrtowcs_l() functions take an explicit locale
     argument, whereas the mbsrtowcs() and mbsnrtowcs() functions use the
     current global or per-thread locale.


RETURN VALUES

     The mbsrtowcs(), mbsrtowcs_l(), mbsnrtowcs(), and mbsnrtowcs_l()
     functions return the number of wide characters stored in the array
     pointed to by dst if successful, otherwise they return (size_t)-1.


ERRORS

     The mbsrtowcs(), mbsrtowcs_l(), mbsnrtowcs(), and mbsnrtowcs_l()
     functions will fail if:

     [EILSEQ]           An invalid multibyte character sequence was
                        encountered.

     [EINVAL]           The conversion state is invalid.


SEE ALSO

     mbrtowc(3), mbstowcs(3), multibyte(3), wcsrtombs(3), xlocale(3)


STANDARDS

     The mbsrtowcs() function conforms to ISO/IEC 9899:1999 (``ISO C99'').

     The mbsrtowcs_l(), mbsnrtowcs(), and mbsnrtowcs_l() functions are an
     extension to the standard.

DragonFly 3.7                  December 26, 2013                 DragonFly 3.7

Search: Section: