From 58f36fba61802f18fe8d9649f93bd765c69d4e2b Mon Sep 17 00:00:00 2001
From: Thomas Voss <mail@thomasvoss.com>
Date: Sun, 10 Mar 2024 18:39:51 +0100
Subject: Add the bufalloc(3) and bufalloc_noterm(3) manuals

---
 man/bufalloc.3        | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++
 man/bufalloc_noterm.3 |  1 +
 2 files changed, 91 insertions(+)
 create mode 100644 man/bufalloc.3
 create mode 100644 man/bufalloc_noterm.3

diff --git a/man/bufalloc.3 b/man/bufalloc.3
new file mode 100644
index 0000000..5f4611c
--- /dev/null
+++ b/man/bufalloc.3
@@ -0,0 +1,90 @@
+.Dd March 10 2024
+.Dt BUFALLOC 3
+.Os
+.Sh NAME
+.Nm bufalloc ,
+.Nm bufalloc_noterm
+.Nd allocate dynamic memory
+.Sh LIBRARY
+.Lb mlib
+.Sh SYNOPSIS
+.In alloc.h
+.Ft "[[gnu::returns_nonnull]] void *"
+.Fn bufalloc "void *p" "size_t n" "size_t m"
+.Ft "void *"
+.Fn bufalloc_noterm "void *p" "size_t n" "size_t m"
+.Sh DESCRIPTION
+The
+.Fn bufalloc
+function resizes the dynamically-allocated buffer pointed to by
+.Fa p
+to be large enough for an array of
+.Fa n
+elements, each of which is
+.Fa m
+bytes in size.
+If the buffer to be resized is
+.Dv nullptr
+then a freshly-allocated buffer is returned instead.
+.Pp
+On error
+.Pq including buffer-size overflow
+the
+.Fn bufalloc
+function prints a diagnostic to the standard output and terminates
+execution.
+.Pp
+The
+.Fn bufalloc_noterm
+function is identical to
+.Fn bufalloc
+except on error it returns
+.Dv nullptr
+instead of printing a diagnostic and terminating.
+.Sh RETURN VALUES
+The
+.Fn bufalloc
+function returns a pointer to the newly allocated- or resized buffer.
+.Pp
+The
+.Fn bufalloc
+function returns a pointer to the newly allocated- or resized buffer if
+successful;
+otherwise the value
+.Dv nullptr
+is returned and the global variable
+.Va errno
+is set to indicate the error.
+.Sh EXAMPLES
+The following calls to
+.Fn bufalloc
+first allocate a buffer to hold 5 values of type
+.Vt int
+and then resize it to hold 10 values of the same type.
+.Bd -literal -offset indent
+int *p = bufalloc(nullptr, 5, sizeof(int));
+p[0] = 69;
+p[1] = 420;
+
+/* … */
+
+p = bufalloc(p, 10, sizeof(int));
+p[9] = 1337;
+.Ed
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er EOVERFLOW
+Overflow occured when computing buffer size.
+.El
+.Pp
+The
+.Fn bufalloc_noterm
+function may fail and set the external variable
+.Va errno
+for any of the errors specified for the library function
+.Xr realloc 3 .
+.Sh SEE ALSO
+.Xr realloc 3 ,
+.Xr reallocarray 3
+.Sh AUTHORS
+.An Thomas Voss Aq Mt mail@thomasvoss.com
diff --git a/man/bufalloc_noterm.3 b/man/bufalloc_noterm.3
new file mode 100644
index 0000000..8017542
--- /dev/null
+++ b/man/bufalloc_noterm.3
@@ -0,0 +1 @@
+.so bufalloc.3
-- 
cgit v1.2.3