[src/trunk]: src/lib/libc/stdlib reallocarr(3): Clarify semantics.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7a1e20ac6278
branches:  trunk
changeset: 369774:7a1e20ac6278
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Wed Aug 31 12:10:05 2022 +0000

description:
reallocarr(3): Clarify semantics.

diffstat:

 lib/libc/stdlib/reallocarr.3 |  118 +++++++++++++++++++++++++++++++++++-------
 1 files changed, 97 insertions(+), 21 deletions(-)

diffs (147 lines):

diff -r 3e0fa844f1eb -r 7a1e20ac6278 lib/libc/stdlib/reallocarr.3
--- a/lib/libc/stdlib/reallocarr.3      Wed Aug 31 05:24:41 2022 +0000
+++ b/lib/libc/stdlib/reallocarr.3      Wed Aug 31 12:10:05 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: reallocarr.3,v 1.4 2015/07/28 17:13:34 kamil Exp $
+.\"    $NetBSD: reallocarr.3,v 1.5 2022/08/31 12:10:05 riastradh Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -36,41 +36,117 @@
 .In stdlib.h
 .Ft int
 .Fo reallocarr
-.Fa "void *ptr"
+.Fa "void *ptrp"
 .Fa "size_t number"
 .Fa "size_t size"
 .Fc
 .Sh DESCRIPTION
 The
 .Nm
-function reallocates the memory in
-.Fa *ptr .
+function safely allocates, resizes, or frees arrays in memory.
+.Pp
+If
+.Fa ptr
+is a null pointer, or a pointer to memory previously allocated with
+.Nm ,
+then
+.Fo reallocarr
+.Li & Ns Fa ptr ,
+.Fa number ,
+.Fa size
+.Fc
+allocates or reallocates the memory that
+.Fa ptr
+points to, possibly moving it to a different location in memory, so
+that it has space for an array of
+.Fa number
+elements of
+.Fa size
+bytes apiece.
+.Nm
+updates
+.Fa ptr
+in case it was moved on success, and leaves it unchanged on failure.
+.Pp
+If
+.Fa ptr
+was previously allocated, the objects stored at
+.Fa ptr Ns Li "[0]" ,
+.Fa ptr Ns Li "[1]" ,
+\&...,
+up to the shorter of its old
+.Fa number
+and its new
+.Fa number ,
+are copied into the new memory, like
+.Xr realloc 3 .
+.Pp
+.Fa ptr
+may be null and
+.Fa number
+may be zero.
+.Fa size
+must be nonzero.
+.Pp
+The memory allocated by
+.Nm
+may be freed with
+.Fo reallocarr
+.Li & Ns Fa ptr ,
+.Li 0 ,
+.Fa size
+.Fc ,
+which will always succeed and unconditionally set
+.Fa ptr
+to null.
+.Pp
+The
+.Nm
+function may alter
+.Va errno
+as a side effect.
+.Pp
+Note that the argument
+.Fa ptrp
+is a pointer to a pointer to allocated memory, unlike
+.Xr realloc
+which takes a pointer to allocated memory.
 .Sh RETURN VALUES
 On successful completion,
-.Fn
+.Nm
 returns 0 and updates
-.Fa *ptr .
-Otherwise, an error code (see
-.Xr errno 2 )
-is returned and
-.Fa *ptr
-and the referenced memory is unmodified.
+.Fa ptr .
+Otherwise, an
+.Xr errno 2
+is returned, and
+.Fa ptr
+and the memory it points to are unmodified.
 .Sh EXAMPLES
 The following uses
 .Fn reallocarr
-to initialize an array of INITSIZE integers, then
-resizes it to NEWSIZE elements:
+to initialize an array of
+.Dv INITSIZE
+integers, then
+resizes it to
+.Dv NEWSIZE
+elements, and finally frees it:
 .Bd -literal -offset indent
 int *data = NULL;
-int ret = 0;
+int error = 0;
 
-ret = reallocarr(&data, INITSIZE, sizeof(*data));
-if (ret)
-    errc(1, ret, "reallocarr failed");
-
-ret = reallocarr(&data, NEWSIZE, sizeof(*data));
-if (ret)
-    errc(1, ret, "reallocarr failed on resize");
+/* allocate */
+error = reallocarr(&data, INITSIZE, sizeof(*data));
+if (error)
+       errc(1, error, "reallocarr failed");
+\&...
+/* resize */
+error = reallocarr(&data, NEWSIZE, sizeof(*data));
+if (error)
+       errc(1, error, "reallocarr failed on resize");
+\&...
+/* free */
+(void)reallocarr(&data, 0, sizeof(*data));
+assert(data == NULL);
 .Ed
 .Sh SEE ALSO
 .Xr calloc 3