[apple/libc.git] / locale / FreeBSD / mbrtowc.3

.\" Copyright (c) 2002 Tim J. Robbins
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/locale/mbrtowc.3,v 1.3 2002/11/29 17:35:09 ru Exp $
.\"
.Dd August 15, 2002
.Dt MBRTOWC 3
.Os
.Sh NAME
.Nm mbrtowc
.Nd "convert a character to a wide-character code (restartable)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In wchar.h
.Ft size_t
.Fo mbrtowc
.Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
.Fa "mbstate_t * restrict ps"
.Fc
.Sh DESCRIPTION
The
.Fn mbrtowc
function inspects at most
.Fa n
bytes pointed to by
.Fa s
and interprets them as a multibyte character sequence
according to the current setting of
.Ev LC_CTYPE .
If
.Fa pwc
is not
.Dv NULL ,
the multibyte character which
.Fa s
represents is stored in the
.Vt wchar_t
it points to.
.Pp
If
.Fa s
is
.Dv NULL ,
.Fn mbrtowc
behaves as if
.Fa pwc
was
.Dv NULL ,
.Fa s
was an empty string
.Pq Qq
and
.Fa n
was 1.
.Pp
The
.Vt mbstate_t
argument,
.Fa ps ,
is used to keep track of the shift state.
If it is
.Dv NULL ,
.Fn mbrtowc
uses an internal, static
.Vt mbstate_t
object.
.Sh RETURN VALUES
The
.Fn mbrtowc
functions returns:
.Bl -tag -width indent
.It 0
The first
.Fa n
or fewer bytes of
.Fa s
represent the null wide character
.Pq Li "L'\e0'" .
.It >0
The first
.Fa n
or fewer bytes of
.Fa s
represent a valid character,
.Fn mbrtowc
returns the length (in bytes) of the multibyte sequence.
.It Po Vt size_t Pc Ns \-2
The first
.Fa n
bytes of
.Fa s
are an incomplete multibyte sequence.
.It Po Vt size_t Pc Ns \-1
The byte sequence pointed to by
.Fa s
is an invalid multibyte sequence.
.El
.Sh ERRORS
The
.Fn mbrtowc
function will fail if:
.Bl -tag -width Er
.\".It Bq Er EINVAL
.\"Invalid argument.
.It Bq Er EILSEQ
An invalid multibyte sequence was detected.
.El
.Sh SEE ALSO
.Xr mbtowc 3 ,
.Xr setlocale 3 ,
.Xr wcrtomb 3
.Sh STANDARDS
The
.Fn mbrtowc
function conforms to
.St -isoC-99 .
.Sh BUGS
The current implementation does not support shift states.
Commit	Line	Data
9385eb3d A	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	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	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: src/lib/libc/locale/mbrtowc.3,v 1.3 2002/11/29 17:35:09 ru Exp $
	26	.\"
	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
	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
	43	The
	44	.Fn mbrtowc
	45	function inspects at most
	46	.Fa n
	47	bytes pointed to by
	48	.Fa s
	49	and interprets them as a multibyte character sequence
	50	according to the current setting of
	51	.Ev LC_CTYPE .
	52	If
	53	.Fa pwc
	54	is not
	55	.Dv NULL ,
	56	the multibyte character which
	57	.Fa s
	58	represents is stored in the
	59	.Vt wchar_t
	60	it points to.
	61	.Pp
	62	If
	63	.Fa s
	64	is
65	.Dv NULL ,
66	.Fn mbrtowc
67	behaves as if
68	.Fa pwc
69	was
70	.Dv NULL ,
71	.Fa s
72	was an empty string
73	.Pq Qq
74	and
75	.Fa n
76	was 1.
77	.Pp
78	The
79	.Vt mbstate_t
80	argument,
81	.Fa ps ,
82	is used to keep track of the shift state.
83	If it is
84	.Dv NULL ,
85	.Fn mbrtowc
86	uses an internal, static
87	.Vt mbstate_t
88	object.
89	.Sh RETURN VALUES
90	The
91	.Fn mbrtowc
92	functions returns:
93	.Bl -tag -width indent
94	.It 0
95	The first
96	.Fa n
97	or fewer bytes of
98	.Fa s
99	represent the null wide character
100	.Pq Li "L'\e0'" .
101	.It >0
102	The first
103	.Fa n
104	or fewer bytes of
105	.Fa s
106	represent a valid character,
107	.Fn mbrtowc
108	returns the length (in bytes) of the multibyte sequence.
109	.It Po Vt size_t Pc Ns \-2
110	The first
111	.Fa n
112	bytes of
113	.Fa s
114	are an incomplete multibyte sequence.
115	.It Po Vt size_t Pc Ns \-1
116	The byte sequence pointed to by
117	.Fa s
118	is an invalid multibyte sequence.
119	.El
120	.Sh ERRORS
121	The
122	.Fn mbrtowc
123	function will fail if:
124	.Bl -tag -width Er
125	.\".It Bq Er EINVAL
126	.\"Invalid argument.
127	.It Bq Er EILSEQ
128	An invalid multibyte sequence was detected.
129	.El
130	.Sh SEE ALSO
131	.Xr mbtowc 3 ,
132	.Xr setlocale 3 ,
133	.Xr wcrtomb 3
134	.Sh STANDARDS
135	The
136	.Fn mbrtowc
137	function conforms to
138	.St -isoC-99 .
139	.Sh BUGS
140	The current implementation does not support shift states.