1MBSNRTOWCS(3)              Linux Programmer's Manual             MBSNRTOWCS(3)
2
3
4

NAME

6       mbsnrtowcs - convert a multibyte string to a wide character string
7

SYNOPSIS

9       #include <wchar.h>
10
11       size_t mbsnrtowcs(wchar_t *dest, const char **src,
12                          size_t nms, size_t len, mbstate_t *ps);
13

DESCRIPTION

15       The mbsnrtowcs() function is like the mbsrtowcs() function, except that
16       the number of bytes to be converted, starting at *src,  is  limited  to
17       nms.
18
19       If  dest  is  not a NULL pointer, the mbsnrtowcs() function converts at
20       most nms bytes from the  multibyte  string  *src  to  a  wide-character
21       string  starting  at  dest.  At most len wide characters are written to
22       dest. The shift state *ps is updated.  The  conversion  is  effectively
23       performed by repeatedly calling mbrtowc(dest,*src,n,ps) where n is some
24       positive number, as long as this call succeeds, and  then  incrementing
25       dest  by  one  and *src by the number of bytes consumed. The conversion
26       can stop for three reasons:
27
28       1. An invalid multibyte sequence has been  encountered.  In  this  case
29       *src  is  left pointing to the invalid multibyte sequence, (size_t)(-1)
30       is returned, and errno is set to EILSEQ.
31
32       2. The nms limit forces a stop, or len non-L'\0' wide  characters  have
33       been  stored  at  dest.  In this case *src is left pointing to the next
34       multibyte sequence to be converted, and the number of  wide  characters
35       written to dest is returned.
36
37       3.  The  multibyte  string has been completely converted, including the
38       terminating '\0' (which has the side effect of bringing back *ps to the
39       initial  state).  In  this  case *src is set to NULL, and the number of
40       wide characters written to dest, excluding the terminating L'\0'  char‐
41       acter, is returned.
42
43       If  dest is NULL, len is ignored, and the conversion proceeds as above,
44       except that the converted wide characters are not written out  to  mem‐
45       ory, and that no destination length limit exists.
46
47       In both of the above cases, if ps is a NULL pointer, a static anonymous
48       state only known to the mbsnrtowcs function is used instead.
49
50       The programmer must ensure that there is room for  at  least  len  wide
51       characters at dest.
52

RETURN VALUE

54       The  mbsnrtowcs()  function  returns the number of wide characters that
55       make up the converted part of the wide character string, not  including
56       the  terminating  null wide character. If an invalid multibyte sequence
57       was encountered, (size_t)(-1) is returned, and errno set to EILSEQ.
58

CONFORMING TO

60       This function is a GNU extension.
61

SEE ALSO

63       iconv(3), mbsrtowcs(3)
64

NOTES

66       The behaviour of mbsnrtowcs() depends on the LC_CTYPE category  of  the
67       current locale.
68
69       Passing NULL as ps is not multi-thread safe.
70
71
72
73GNU                               1999-07-25                     MBSNRTOWCS(3)