ref: 41390429613c2d8ffd2abae7e88d71ef9bfda362
parent: 313e86a65b33fb0c9f4c05789e2e93de19fb61bc
author: Roberto E. Vargas Caballero <k0ga@shike2.com>
date: Wed Mar 16 08:24:59 EDT 2022
doc: Add man page for mbtowc()
--- /dev/null
+++ b/doc/man3/mbtowc.3
@@ -1,0 +1,69 @@
+.TH MBTOWC 3
+.SH NAME
+mbtowc - converts from multibyte encoding to wchar_t
+.SH SYNOPSIS
+#include <stdlib.h>
+
+int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n)
+.SH DESCRIPTION
+if
+.I s
+is not a null pointer,
+the
+.BR mbtowc ()
+function inspects at most
+.I n
+bytes beginning with the byte pointed to by
+.I s
+to determine the number of bytes needed
+to complete the next multibyte character
+(including any shift sequences).
+If the function determines
+that the next multibyte character is complete and valid,
+it determines the value of the corresponding wide character
+and then,
+if
+.I pwc
+is not a null pointer,
+stores that value in the object pointed to by
+.IR pwc .
+If the corresponding wide character is the null wide character,
+the function is left in the initial conversion state.
+.SH RETURN VALUE
+If
+.I s
+is a null pointer,
+the
+.BR mbtowc ()
+function returns a nonzero or zero value,
+if multibyte character encodings,
+respectively,
+do or do not have state-dependent encodings.
+If
+.I s
+is not a null pointer,
+the
+.BR mbtowc ()
+function either returns 0
+(if
+.I s
+points to the null character),
+or returns the number of bytes
+that are contained in the converted multibyte character
+(if the next
+.I n
+or fewer bytes form a valid multibyte character),
+or returns -1
+(if they do not form a valid multibyte character).
+.PP
+In no case will the value returned be
+greater than
+.I n
+or the value of the
+.I MB_CUR_MAX
+macro.
+.SH STANDARDS
+ISO/IEC 9899:1999 Section 7.20.7.2 Paragraph 1,2,3,4,5
+.SH SEE ALSO
+.BR stdlib.h (3)
+.BR wchar.h (3)