mbrtowc.3 (58d38e25205c6ee5ef0796ffa2cd8e2ca6c6e7f3) mbrtowc.3 (279062fae149e105dae7c28b638d49ba5715725d)
1.\" Copyright (c) 2002 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.

--- 9 unchanged lines hidden (view full) ---

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$
1.\" Copyright (c) 2002 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.

--- 9 unchanged lines hidden (view full) ---

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$
26.\"
26.Dd August 15, 2002
27.Dt MBRTOWC 3
28.Os
29.Sh NAME
30.Nm mbrtowc
31.Nd "convert a character to a wide-character code (restartable)"
32.Sh LIBRARY
33.Lb libc
34.Sh SYNOPSIS
35.In wchar.h
36.Ft size_t
27.Dd August 15, 2002
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
37.Fn mbrtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
38.Fo mbrtowc
39.Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
40.Fa "mbstate_t * restrict ps"
41.Fc
38.Sh DESCRIPTION
39The
40.Fn mbrtowc
41function inspects at most
42.Fa n
43bytes pointed to by
44.Fa s
45and interprets them as a multibyte character sequence
46according to the current setting of
47.Ev LC_CTYPE .
48If
49.Fa pwc
50is not
51.Dv NULL ,
52the multibyte character which
53.Fa s
54represents is stored in the
42.Sh DESCRIPTION
43The
44.Fn mbrtowc
45function inspects at most
46.Fa n
47bytes pointed to by
48.Fa s
49and interprets them as a multibyte character sequence
50according to the current setting of
51.Ev LC_CTYPE .
52If
53.Fa pwc
54is not
55.Dv NULL ,
56the multibyte character which
57.Fa s
58represents is stored in the
55.Ft wchar_t
59.Vt wchar_t
56it points to.
57.Pp
58If
59.Fa s
60is
61.Dv NULL ,
62.Fn mbrtowc
63behaves as if
64.Fa pwc
65was
66.Dv NULL ,
67.Fa s
60it points to.
61.Pp
62If
63.Fa s
64is
65.Dv NULL ,
66.Fn mbrtowc
67behaves as if
68.Fa pwc
69was
70.Dv NULL ,
71.Fa s
68was an empty string ("")
72was an empty string
73.Pq Qq
69and
70.Fa n
71was 1.
72.Pp
73The
74and
75.Fa n
76was 1.
77.Pp
78The
74.Ft mbstate_t
79.Vt mbstate_t
75argument,
76.Fa ps ,
77is used to keep track of the shift state.
78If it is
79.Dv NULL ,
80.Fn mbrtowc
81uses an internal, static
80argument,
81.Fa ps ,
82is used to keep track of the shift state.
83If it is
84.Dv NULL ,
85.Fn mbrtowc
86uses an internal, static
82.Ft mbstate_t
87.Vt mbstate_t
83object.
84.Sh RETURN VALUES
85The
86.Fn mbrtowc
87functions returns:
88.Bl -tag -width indent
89.It 0
90The first
91.Fa n
92or fewer bytes of
93.Fa s
88object.
89.Sh RETURN VALUES
90The
91.Fn mbrtowc
92functions returns:
93.Bl -tag -width indent
94.It 0
95The first
96.Fa n
97or fewer bytes of
98.Fa s
94represent the null wide character (L'\e0').
99represent the null wide character
100.Pq Li "L'\e0'" .
95.It >0
96The first
97.Fa n
98or fewer bytes of
99.Fa s
100represent a valid character,
101.Fn mbrtowc
102returns the length (in bytes) of the multibyte sequence.
101.It >0
102The first
103.Fa n
104or fewer bytes of
105.Fa s
106represent a valid character,
107.Fn mbrtowc
108returns the length (in bytes) of the multibyte sequence.
103.It Xo
104.No ( Ns
105.Ft size_t Ns
106.No ) Ns \&-2
107.Xc
109.It Po Vt size_t Pc Ns \-2
108The first
109.Fa n
110bytes of
111.Fa s
112are an incomplete multibyte sequence.
110The first
111.Fa n
112bytes of
113.Fa s
114are an incomplete multibyte sequence.
113.It Xo
114.No ( Ns
115.Ft size_t Ns
116.No ) Ns \&-1
117.Xc
115.It Po Vt size_t Pc Ns \-1
118The byte sequence pointed to by
119.Fa s
120is an invalid multibyte sequence.
121.El
122.Sh ERRORS
123The
124.Fn mbrtowc
125function will fail if:

--- 17 unchanged lines hidden --- 		116The byte sequence pointed to by
117.Fa s
118is an invalid multibyte sequence.
119.El
120.Sh ERRORS
121The
122.Fn mbrtowc
123function will fail if:

--- 17 unchanged lines hidden ---