[thirdparty/man-pages.git] / man3 / mbrlen.3

.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   Dinkumware C library reference http://www.dinkumware.com/
.\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
.\"   ISO/IEC 9899:1999
.\"
.TH MBRLEN 3  1999-07-25 "GNU" "Linux Programmer's Manual"
.SH NAME
mbrlen \- determine number of bytes in next multibyte character
.SH SYNOPSIS
.nf
.B #include <wchar.h>
.sp
.BI "size_t mbrlen(const char *" s ", size_t " n ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
The
.BR mbrlen ()
function inspects at most \fIn\fP bytes of the multibyte
string starting at \fIs\fP and extracts the next complete multibyte character.
It updates the shift state \fI*ps\fP.
If the multibyte character is not the
null wide character, it returns the number of bytes that were consumed from
\fIs\fP.
If the multibyte character is the null wide character, it resets the
shift state \fI*ps\fP to the initial state and returns 0.
.PP
If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
character,
.BR mbrlen ()
returns \fI(size_t)(\-2)\fP.
This can happen even if
\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift
sequences.
.PP
If the multibyte string starting at \fIs\fP contains an invalid multibyte
sequence before the next complete character,
.BR mbrlen ()
returns
\fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP.
In this case,
the effects on \fI*ps\fP are undefined.
.PP
If \fIps\fP is a NULL pointer, a static anonymous state only known to the
mbrlen function is used instead.
.SH "RETURN VALUE"
The
.BR mbrlen ()
function returns the number of bytes
parsed from the multibyte
sequence starting at \fIs\fP, if a non-null wide character was recognized.
It returns 0, if a null wide character was recognized.
It returns (size_t)(\-1)
and sets \fIerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was
encountered.
It returns (size_t)(\-2) if it couldn't parse a complete multibyte
character, meaning that \fIn\fP should be increased.
.SH "CONFORMING TO"
C99
.SH NOTES
The behavior of
.BR mbrlen ()
depends on the
.B LC_CTYPE
category of the
current locale.
.SH "SEE ALSO"
.BR mbrtowc (3)
Commit	Line	Data
fea681da MK	1	.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
	2	.\"
	3	.\" This is free documentation; you can redistribute it and/or
	4	.\" modify it under the terms of the GNU General Public License as
	5	.\" published by the Free Software Foundation; either version 2 of
	6	.\" the License, or (at your option) any later version.
	7	.\"
	8	.\" References consulted:
	9	.\" GNU glibc-2 source code and manual
	10	.\" Dinkumware C library reference http://www.dinkumware.com/
	11	.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
	12	.\" ISO/IEC 9899:1999
	13	.\"
	14	.TH MBRLEN 3 1999-07-25 "GNU" "Linux Programmer's Manual"
	15	.SH NAME
	16	mbrlen \- determine number of bytes in next multibyte character
	17	.SH SYNOPSIS
	18	.nf
	19	.B #include <wchar.h>
	20	.sp
	21	.BI "size_t mbrlen(const char " s ", size_t " n ", mbstate_t " ps );
	22	.fi
	23	.SH DESCRIPTION
60a90ecd MK	24	The
	25	.BR mbrlen ()
	26	function inspects at most \fIn\fP bytes of the multibyte
fea681da	27	string starting at \fIs\fP and extracts the next complete multibyte character.
c13182ef MK	28	It updates the shift state \fI*ps\fP.
c13182ef MK	29	If the multibyte character is not the
fea681da	30	null wide character, it returns the number of bytes that were consumed from
c13182ef MK	31	\fIs\fP.
c13182ef MK	32	If the multibyte character is the null wide character, it resets the
fea681da MK	33	shift state \fI*ps\fP to the initial state and returns 0.
	34	.PP
	35	If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
60a90ecd MK	36	character,
	37	.BR mbrlen ()
	38	returns \fI(size_t)(\-2)\fP.
c13182ef	39	This can happen even if
fea681da MK	40	\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift
	41	sequences.
	42	.PP
	43	If the multibyte string starting at \fIs\fP contains an invalid multibyte
60a90ecd MK	44	sequence before the next complete character,
	45	.BR mbrlen ()
	46	returns
c13182ef MK	47	\fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP.
c13182ef MK	48	In this case,
fea681da MK	49	the effects on \fI*ps\fP are undefined.
	50	.PP
	51	If \fIps\fP is a NULL pointer, a static anonymous state only known to the
	52	mbrlen function is used instead.
	53	.SH "RETURN VALUE"
60a90ecd MK	54	The
	55	.BR mbrlen ()
	56	function returns the number of bytes
c13182ef	57	parsed from the multibyte
fea681da	58	sequence starting at \fIs\fP, if a non-null wide character was recognized.
c13182ef MK	59	It returns 0, if a null wide character was recognized.
c13182ef MK	60	It returns (size_t)(\-1)
dcec8eb5	61	and sets \fIerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was
c13182ef MK	62	encountered.
c13182ef MK	63	It returns (size_t)(\-2) if it couldn't parse a complete multibyte
fea681da MK	64	character, meaning that \fIn\fP should be increased.
fea681da MK	65	.SH "CONFORMING TO"
68e1685c	66	C99
fea681da	67	.SH NOTES
d9bfdb9c	68	The behavior of
60a90ecd	69	.BR mbrlen ()
1274071a MK	70	depends on the
	71	.B LC_CTYPE
	72	category of the
fea681da	73	current locale.
e37e3282 MK	74	.SH "SEE ALSO"
e37e3282 MK	75	.BR mbrtowc (3)