summaryrefslogtreecommitdiffstats
path: root/man3/mbrlen.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/mbrlen.3')
-rw-r--r--man3/mbrlen.3131
1 files changed, 131 insertions, 0 deletions
diff --git a/man3/mbrlen.3 b/man3/mbrlen.3
new file mode 100644
index 0000000..bf19f88
--- /dev/null
+++ b/man3/mbrlen.3
@@ -0,0 +1,131 @@
+'\" t
+.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" 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 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+mbrlen \- determine number of bytes in next multibyte character
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <wchar.h>
+.PP
+.BI "size_t mbrlen(const char " s "[restrict ." n "], size_t " n ,
+.BI " mbstate_t *restrict " ps );
+.fi
+.SH DESCRIPTION
+The
+.BR mbrlen ()
+function inspects at most
+.I n
+bytes of the multibyte
+string starting at
+.I s
+and extracts the next complete multibyte character.
+It updates the shift state
+.IR *ps .
+If the multibyte character is not the
+null wide character, it returns the number of bytes that were consumed from
+.IR s .
+If the multibyte character is the null wide character, it resets the
+shift state
+.I *ps
+to the initial state and returns 0.
+.PP
+If the
+.I n
+bytes starting at
+.I s
+do not contain a complete multibyte
+character,
+.BR mbrlen ()
+returns
+.IR "(size_t)\ \-2" .
+This can happen even if
+.I n
+>=
+.IR MB_CUR_MAX ,
+if the multibyte string contains redundant shift
+sequences.
+.PP
+If the multibyte string starting at
+.I s
+contains an invalid multibyte
+sequence before the next complete character,
+.BR mbrlen ()
+returns
+.I (size_t)\ \-1
+and sets
+.I errno
+to
+.BR EILSEQ .
+In this case,
+the effects on
+.I *ps
+are undefined.
+.PP
+If
+.I ps
+is NULL, a static anonymous state known only to the
+.BR mbrlen ()
+function is used instead.
+.SH RETURN VALUE
+The
+.BR mbrlen ()
+function returns the number of bytes
+parsed from the multibyte
+sequence starting at
+.IR s ,
+if a non-null wide character was recognized.
+It returns 0, if a null wide character was recognized.
+It returns
+.I "(size_t)\ \-1"
+and sets
+.I errno
+to
+.BR EILSEQ ,
+if an invalid multibyte sequence was
+encountered.
+It returns
+.I (size_t)\ \-2
+if it couldn't parse a complete multibyte
+character, meaning that
+.I n
+should be increased.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR mbrlen ()
+T} Thread safety MT-Unsafe race:mbrlen/!ps
+.TE
+.sp 1
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 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)