1.\" Copyright (c) 2002-2004 Tim J. Robbins
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
--- 8 unchanged lines hidden (view full) ---
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/lib/libc/locale/mbrtowc.3 216756 2010-12-28 10:08:50Z uqs $
26.\"
27.Dd April 8, 2004
28.Dt MBRTOWC 3
29.Os
30.Sh NAME
31.Nm mbrtowc
32.Nd "convert a character to a wide-character code (restartable)"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wchar.h
37.Ft size_t
38.Fo mbrtowc
39.Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
40.Fa "mbstate_t * restrict ps"
41.Fc
42.Sh DESCRIPTION
43The
44.Fn mbrtowc
45function inspects at most
46.Fa n
47bytes pointed to by
48.Fa s
49to determine the number of bytes needed to complete the next multibyte
50character.
51If a character can be completed, and
52.Fa pwc
53is not
54.Dv NULL ,
55the wide character which is represented by
56.Fa s
57is stored in the
58.Vt wchar_t
59it points to.
60.Pp
61If
62.Fa s
63is
64.Dv NULL ,
65.Fn mbrtowc
66behaves as if
67.Fa pwc
68was
69.Dv NULL ,
70.Fa s
71was an empty string
72.Pq Qq
73and
74.Fa n
75was 1.
76.Pp
77The
78.Vt mbstate_t
79argument,
80.Fa ps ,
81is used to keep track of the shift state.
82If it is
83.Dv NULL ,
84.Fn mbrtowc
85uses an internal, static
86.Vt mbstate_t
87object, which is initialized to the initial conversion state
88at program startup.
89.Sh RETURN VALUES
90The
91.Fn mbrtowc
92functions returns:
93.Bl -tag -width indent
94.It 0
95The next
96.Fa n
97or fewer bytes
98represent the null wide character
99.Pq Li "L'\e0'" .
100.It >0
101The next
102.Fa n
103or fewer bytes
104represent a valid character,
105.Fn mbrtowc
106returns the number of bytes used to complete the multibyte character.
107.It Po Vt size_t Pc Ns \-2
108The next
109.Fa n
110contribute to, but do not complete, a valid multibyte character sequence,
111and all
112.Fa n
113bytes have been processed.
114.It Po Vt size_t Pc Ns \-1
115An encoding error has occurred.
116The next
117.Fa n
118or fewer bytes do not contribute to a valid multibyte character.
119.El
120.Sh ERRORS
121The
122.Fn mbrtowc
123function will fail if:
124.Bl -tag -width Er
125.It Bq Er EILSEQ
126An invalid multibyte sequence was detected.
127.It Bq Er EINVAL
128The conversion state is invalid.
129.El
130.Sh SEE ALSO
131.Xr mbtowc 3 ,
132.Xr multibyte 3 ,
133.Xr setlocale 3 ,
134.Xr wcrtomb 3
135.Sh STANDARDS
136The
137.Fn mbrtowc
138function conforms to
139.St -isoC-99 .
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
--- 8 unchanged lines hidden (view full) ---
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/lib/libc/locale/mbrtowc.3 216756 2010-12-28 10:08:50Z uqs $
26.\"
27.Dd April 8, 2004
28.Dt MBRTOWC 3
29.Os
30.Sh NAME
31.Nm mbrtowc
32.Nd "convert a character to a wide-character code (restartable)"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wchar.h
37.Ft size_t
38.Fo mbrtowc
39.Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
40.Fa "mbstate_t * restrict ps"
41.Fc
42.Sh DESCRIPTION
43The
44.Fn mbrtowc
45function inspects at most
46.Fa n
47bytes pointed to by
48.Fa s
49to determine the number of bytes needed to complete the next multibyte
50character.
51If a character can be completed, and
52.Fa pwc
53is not
54.Dv NULL ,
55the wide character which is represented by
56.Fa s
57is stored in the
58.Vt wchar_t
59it points to.
60.Pp
61If
62.Fa s
63is
64.Dv NULL ,
65.Fn mbrtowc
66behaves as if
67.Fa pwc
68was
69.Dv NULL ,
70.Fa s
71was an empty string
72.Pq Qq
73and
74.Fa n
75was 1.
76.Pp
77The
78.Vt mbstate_t
79argument,
80.Fa ps ,
81is used to keep track of the shift state.
82If it is
83.Dv NULL ,
84.Fn mbrtowc
85uses an internal, static
86.Vt mbstate_t
87object, which is initialized to the initial conversion state
88at program startup.
89.Sh RETURN VALUES
90The
91.Fn mbrtowc
92functions returns:
93.Bl -tag -width indent
94.It 0
95The next
96.Fa n
97or fewer bytes
98represent the null wide character
99.Pq Li "L'\e0'" .
100.It >0
101The next
102.Fa n
103or fewer bytes
104represent a valid character,
105.Fn mbrtowc
106returns the number of bytes used to complete the multibyte character.
107.It Po Vt size_t Pc Ns \-2
108The next
109.Fa n
110contribute to, but do not complete, a valid multibyte character sequence,
111and all
112.Fa n
113bytes have been processed.
114.It Po Vt size_t Pc Ns \-1
115An encoding error has occurred.
116The next
117.Fa n
118or fewer bytes do not contribute to a valid multibyte character.
119.El
120.Sh ERRORS
121The
122.Fn mbrtowc
123function will fail if:
124.Bl -tag -width Er
125.It Bq Er EILSEQ
126An invalid multibyte sequence was detected.
127.It Bq Er EINVAL
128The conversion state is invalid.
129.El
130.Sh SEE ALSO
131.Xr mbtowc 3 ,
132.Xr multibyte 3 ,
133.Xr setlocale 3 ,
134.Xr wcrtomb 3
135.Sh STANDARDS
136The
137.Fn mbrtowc
138function conforms to
139.St -isoC-99 .