mbrlen.3 (7183f43d9543e724830f9895f32fd681be00b776) mbrlen.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 November 11, 2002
27.Dt MBRLEN 3
28.Os
29.Sh NAME
30.Nm mbrlen
31.Nd "get number of bytes in a character (restartable)"
32.Sh LIBRARY
33.Lb libc
34.Sh SYNOPSIS
35.In wchar.h
36.Ft size_t
37.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
38.Sh DESCRIPTION
39The
40.Fn mbrlen
27.Dd November 11, 2002
28.Dt MBRLEN 3
29.Os
30.Sh NAME
31.Nm mbrlen
32.Nd "get number of bytes in a character (restartable)"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wchar.h
37.Ft size_t
38.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
39.Sh DESCRIPTION
40The
41.Fn mbrlen
41function determines the the number of bytes constituting the
42function determines the number of bytes constituting the
42multibyte character sequence pointed to by
43.Fa s ,
44examining at most
45.Fa n
46bytes.
47.Pp
48The
43multibyte character sequence pointed to by
44.Fa s ,
45examining at most
46.Fa n
47bytes.
48.Pp
49The
49.Ft mbstate_t
50.Vt mbstate_t
50argument,
51.Fa ps ,
52is used to keep track of the shift state.
53If it is
54.Dv NULL ,
55.Fn mbrlen
56uses an internal, static
51argument,
52.Fa ps ,
53is used to keep track of the shift state.
54If it is
55.Dv NULL ,
56.Fn mbrlen
57uses an internal, static
57.Ft mbstate_t
58.Vt mbstate_t
58object.
59.Pp
60It is equivalent to:
61.Pp
62.Dl "mbrtowc(NULL, s, n, ps);"
63.Pp
64Except that when
65.Fa ps
59object.
60.Pp
61It is equivalent to:
62.Pp
63.Dl "mbrtowc(NULL, s, n, ps);"
64.Pp
65Except that when
66.Fa ps
66is a NULL pointer,
67is a
68.Dv NULL
69pointer,
67.Fn mbrlen
68uses its own static, internal
70.Fn mbrlen
71uses its own static, internal
69.Ft mbstate_t
70object to keep track of shift state.
72.Vt mbstate_t
73object to keep track of the shift state.
71.Sh RETURN VALUES
72The
73.Fn mbrlen
74functions returns:
75.Bl -tag -width indent
76.It 0
77The first
78.Fa n
79or fewer bytes of
80.Fa s
74.Sh RETURN VALUES
75The
76.Fn mbrlen
77functions returns:
78.Bl -tag -width indent
79.It 0
80The first
81.Fa n
82or fewer bytes of
83.Fa s
81represent the null wide character (L'\e0').
84represent the null wide character
85.Pq Li "L'\e0'" .
82.It >0
83The first
84.Fa n
85or fewer bytes of
86.Fa s
87represent a valid character,
88.Fn mbrtowc
89returns the length (in bytes) of the multibyte sequence.
86.It >0
87The first
88.Fa n
89or fewer bytes of
90.Fa s
91represent a valid character,
92.Fn mbrtowc
93returns the length (in bytes) of the multibyte sequence.
90.It Xo
91.No ( Ns
92.Ft size_t Ns
93.No ) Ns \&-2
94.Xc
94.It Po Vt size_t Pc Ns \-2
95The first
96.Fa n
97bytes of
98.Fa s
99are an incomplete multibyte sequence.
95The first
96.Fa n
97bytes of
98.Fa s
99are an incomplete multibyte sequence.
100.It Xo
101.No ( Ns
102.Ft size_t Ns
103.No ) Ns \&-1
104.Xc
100.It Po Vt size_t Pc Ns \-1
105The byte sequence pointed to by
106.Fa s
107is an invalid multibyte sequence.
108.El
109.Sh EXAMPLES
110A function which calculates the number of characters in a multibyte
111character string:
112.Bd -literal -offset indent

--- 37 unchanged lines hidden --- 		101The byte sequence pointed to by
102.Fa s
103is an invalid multibyte sequence.
104.El
105.Sh EXAMPLES
106A function which calculates the number of characters in a multibyte
107character string:
108.Bd -literal -offset indent

--- 37 unchanged lines hidden ---