mbsrtowcs(3)

1mbsrtowcs(3)               Library Functions Manual               mbsrtowcs(3)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <wchar.h>
13
14       size_t mbsrtowcs(wchar_t dest[restrict .len], const char **restrict src,
15                        size_t len, mbstate_t *restrict ps);
16

DESCRIPTION

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

RETURN VALUE

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

ATTRIBUTES

58       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
59       tributes(7).
60
61       ┌────────────┬───────────────┬─────────────────────────────────────────┐
62       │Interface   │ Attribute     │ Value                                   │
63       ├────────────┼───────────────┼─────────────────────────────────────────┤
64       │mbsrtowcs() │ Thread safety │ MT-Unsafe race:mbsrtowcs/!ps            │
65       └────────────┴───────────────┴─────────────────────────────────────────┘
66

STANDARDS

68       C11, POSIX.1-2008.
69

HISTORY

71       POSIX.1-2001, C99.
72

NOTES

74       The behavior of mbsrtowcs() depends on the  LC_CTYPE  category  of  the
75       current locale.
76
77       Passing NULL as ps is not multithread safe.
78