mbtowc.3 (bc0b3a180015087b0d8d3a1e4e4f881271d209f0) mbtowc.3 (8b8109275c1a583e96171df08e3136151c02279e)
1.\" Copyright (c) 2002, 2003 Tim J. Robbins. All rights reserved.
1.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved.
2.\" Copyright (c) 1993
3.\" The Regents of the University of California. All rights reserved.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" Donn Seeley of BSDI.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions

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

32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93
37.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp
38.\" $FreeBSD$
39.\"
2.\" Copyright (c) 1993
3.\" The Regents of the University of California. All rights reserved.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" Donn Seeley of BSDI.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions

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

32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93
37.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp
38.\" $FreeBSD$
39.\"
40.Dd November 19, 2003
40.Dd April 7, 2004
41.Dt MBTOWC 3
42.Os
43.Sh NAME
44.Nm mbtowc
45.Nd convert a character to a wide-character code
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In stdlib.h
50.Ft int
51.Fn mbtowc "wchar_t * restrict wcharp" "const char * restrict mbchar" "size_t nbytes"
52.Sh DESCRIPTION
53The
54.Fn mbtowc
55function converts a multibyte character
56.Fa mbchar
41.Dt MBTOWC 3
42.Os
43.Sh NAME
44.Nm mbtowc
45.Nd convert a character to a wide-character code
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In stdlib.h
50.Ft int
51.Fn mbtowc "wchar_t * restrict wcharp" "const char * restrict mbchar" "size_t nbytes"
52.Sh DESCRIPTION
53The
54.Fn mbtowc
55function converts a multibyte character
56.Fa mbchar
57into a wide character and stores the result
57into a wide character according to the current conversion state,
58and stores the result
58in the object pointed to by
59.Fa wcharp .
60Up to
61.Fa nbytes
62bytes are examined.
63.Pp
64A call with a null
65.Fa mbchar
59in the object pointed to by
60.Fa wcharp .
61Up to
62.Fa nbytes
63bytes are examined.
64.Pp
65A call with a null
66.Fa mbchar
66pointer returns nonzero if the current locale requires shift states,
67pointer returns nonzero if the current encoding requires shift states,
67zero otherwise;
68if shift states are required, the shift state is reset to the initial state.
69.Sh RETURN VALUES
70If
71.Fa mbchar
72is
73.Dv NULL ,
74the
75.Fn mbtowc
76function returns nonzero if shift states are supported,
77zero otherwise.
68zero otherwise;
69if shift states are required, the shift state is reset to the initial state.
70.Sh RETURN VALUES
71If
72.Fa mbchar
73is
74.Dv NULL ,
75the
76.Fn mbtowc
77function returns nonzero if shift states are supported,
78zero otherwise.
78If
79.Pp
80Otherwise, if
79.Fa mbchar
81.Fa mbchar
80is valid,
82is not a null pointer,
81.Fn mbtowc
82returns
83the number of bytes processed in
84.Fa mbchar ,
85or \-1 if no multibyte character
86could be recognized or converted.
83.Fn mbtowc
84returns
85the number of bytes processed in
86.Fa mbchar ,
87or \-1 if no multibyte character
88could be recognized or converted.
89In this case,
90.Fn mbtowc Ns No 's
91internal conversion state is undefined.
87.Sh ERRORS
88The
89.Fn mbtowc
90function will fail if:
91.Bl -tag -width Er
92.Sh ERRORS
93The
94.Fn mbtowc
95function will fail if:
96.Bl -tag -width Er
92.\".It Bq Er EINVAL
93.\"Invalid argument.
94.It Bq Er EILSEQ
95An invalid multibyte sequence was detected.
97.It Bq Er EILSEQ
98An invalid multibyte sequence was detected.
99.It Bq Er EINVAL
100The internal conversion state is invalid.
96.El
97.Sh SEE ALSO
98.Xr btowc 3 ,
99.Xr mblen 3 ,
100.Xr mbrtowc 3 ,
101.Xr mbstowcs 3 ,
101.El
102.Sh SEE ALSO
103.Xr btowc 3 ,
104.Xr mblen 3 ,
105.Xr mbrtowc 3 ,
106.Xr mbstowcs 3 ,
107.Xr multibyte 3 ,
102.Xr wctomb 3
103.Sh STANDARDS
104The
105.Fn mbtowc
106function conforms to
108.Xr wctomb 3
109.Sh STANDARDS
110The
111.Fn mbtowc
112function conforms to
107.St -isoC .
108.Sh BUGS
109The current implementation does not support shift states.
113.St -isoC-99 .