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