Module Name: src
Committed By: riastradh
Date: Wed Aug 31 12:10:05 UTC 2022
Modified Files:
src/lib/libc/stdlib: reallocarr.3
Log Message:
reallocarr(3): Clarify semantics.
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/lib/libc/stdlib/reallocarr.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/stdlib/reallocarr.3
diff -u src/lib/libc/stdlib/reallocarr.3:1.4 src/lib/libc/stdlib/reallocarr.3:1.5
--- src/lib/libc/stdlib/reallocarr.3:1.4 Tue Jul 28 17:13:34 2015
+++ src/lib/libc/stdlib/reallocarr.3 Wed Aug 31 12:10:05 2022
@@ -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;
-
-ret = reallocarr(&data, INITSIZE, sizeof(*data));
-if (ret)
- errc(1, ret, "reallocarr failed");
+int error = 0;
-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
