Begin adding manual pages

1 files changed, 69 insertions, 0 deletions

diff --git a/man/rtou8.3 b/man/rtou8.3
new file mode 100644
index 0000000..0803e84
--- /dev/null
+++ b/man/rtou8.3
@@ -0,0 +1,69 @@
+.Dd March 10 2024
+.Dt RTOU8 3
+.Os
+.Sh NAME
+.Nm rtou8
+.Nd encode a rune to UTF-8
+.Sh LIBRARY
+.Lb mlib
+.Sh SYNOPSIS
+.In mbstring.h
+.Ft int
+.Fn rtou8 "char8_t *s" "size_t n" "rune ch"
+.Sh DESCRIPTION
+The
+.Fn rtou8
+function writes the rune
+.Fa ch
+to the UTF-8 encoded buffer
+.Fa s
+of length
+.Fa n ,
+returning the number of bytes required to UTF-8 encode
+.Fa ch .
+If
+.Fa s
+is too small,
+no data is written to it but the number of bytes required to UTF-8 encode
+.Fa ch
+is still returned.
+.Pp
+An invalid rune is treated as if it were
+.Dv RUNE_ERROR .
+.Sh RETURN VALUES
+The
+.Fn rtou8
+function returns the number of bytes required to write
+.Fa ch
+to the buffer
+.Fa s .
+.Sh EXAMPLES
+The following call to
+.Fn rtou8
+is used to print a rune to the standard output.
+.Bd -literal -offset indent
+#include <rune.h> /* For PRIXRUNE; see rune(3) */
+
+rune ch = U\(aqĦ\(aq;
+
+char buf[U8_LEN_MAX];
+int w = rtou8(buf, sizeof(buf), ch);
+
+/* U+0126: ‘Ħ’ */
+printf(\(dqU+%04\(dq PRIXRUNE \(dq: ‘%.*s’\en\(dq, ch, w, buf);
+.Ed
+.Sh SEE ALSO
+.Xr rune 3 ,
+.Xr u8tor 3 ,
+.Xr RUNE_ERROR 3const ,
+.Xr unicode 7 ,
+.Xr utf\-8 7
+.Sh STANDARDS
+.Rs
+.%A F. Yergeau
+.%D November 2003
+.%R RFC 3629
+.%T UTF-8, a transformation format of ISO 10646
+.Re
+.Sh AUTHORS
+.An Thomas Voss Aq Mt mail@thomasvoss.com