aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAlejandro Colomar <alx@kernel.org>2023-02-25 02:52:42 +0100
committerAlejandro Colomar <alx@kernel.org>2023-02-25 02:52:44 +0100
commit6d50f6aaccb69eaa82ea5c44f7ba6b3e1e3f2491 (patch)
tree670b33e0ef64d1cf15f295c7a4b2854e5f029d5c
parent94a499f7fb1bd2e1d8739f29071738ac93855654 (diff)
downloadman-pages-6d50f6aaccb69eaa82ea5c44f7ba6b3e1e3f2491.tar.gz
malloc.3: EXAMPLES: Add example program with mallocarray() and macros
mallocarray() is safer than malloc(3), since it checks for overflow; it should be preferred almost always (with the exception of non-arrays maybe). The macros like MALLOCARRAY() --and MALLOC()-- that perform automatic casting and sizeof() are also safer than calling the functions directly: - The type of the allocated object (not the pointer) is specified as an argument, which improves readability: - It is directly obvious what is the type of the object just by reading the macro call. - It allows grepping for all allocations of a given type. This is admittedly similar to using sizeof() to get the size of the object, but we'll see why this is better. - In the case of reallocation macros, an extra check is performed to make sure that the previous pointer was compatible with the allocated type, which can avoid some mistakes. - The cast is performed automatically, with a pointer type derived from the type of the object. This is the best point of this macro, since it does an automatic cast, where there's no chance of typos. Usually, programmers have to decide whether to cast or not the result of malloc(3). Casts usually hide warnings, so are to be avoided. However, these functions already return a void *, so a cast doesn't really add much danger. Moreover, a cast can even add warnings in this exceptional case, if the type of the cast is different than the type of the assigned pointer. Performing a manual cast is still not perfect, since there are chances that a mistake will be done, and even ignoring accidents, they clutter code, hurting readability. And now we have a cast that is synced with sizeof. - Whenever the type of the object changes, since we perform an explicit cast to the old type, there will be a warning due to type mismatch in the assignment, so we'll be able to see all lines that are affected by such a change. This is especially important, since changing the type of a variable and missing to update an allocation call far away from the declaration is easy, and the consequences can be quite bad Apart from those benefits, there are other minor style benefits: - Consistency in getting the size of the object from sizeof(type), instead of a mix of sizeof(type) sometimes and sizeof(*p) other times. - More readable code: no casts, and no sizeof(), so also shorter lines that we don't need to cut. - Consistency in using array allocation calls for allocations of arrays of objects, even when the object size is 1. Link: <https://github.com/shadow-maint/shadow/pull/649> Cc: Serge Hallyn <serge@hallyn.com> Cc: Iker Pedrosa <ipedrosa@redhat.com> Cc: "Valentin V. Bartenev" <vbartenev@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
-rw-r--r--man3/malloc.332
1 files changed, 32 insertions, 0 deletions
diff --git a/man3/malloc.3 b/man3/malloc.3
index 4261a6df29..21f537dd5e 100644
--- a/man3/malloc.3
+++ b/man3/malloc.3
@@ -381,6 +381,38 @@ as POSIX and the C standard do not allow replacement of
.BR calloc (),
and
.BR realloc ().
+.SH EXAMPLES
+.EX
+#include <err.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type)))
+#define MALLOC(type) MALLOCARRAY(1, type)
+
+static inline void *my_mallocarray(size_t nmemb, size_t size);
+
+int
+main(void)
+{
+ char *p;
+
+ p = MALLOCARRAY(32, char);
+ if (p == NULL)
+ err(EXIT_FAILURE, "malloc");
+
+ strlcpy(p, "foo", 32);
+ puts(p);
+}
+
+static inline void *
+my_mallocarray(size_t nmemb, size_t size)
+{
+ return reallocarray(NULL, nmemb, size);
+}
+.EE
.SH SEE ALSO
.\" http://g.oswego.edu/dl/html/malloc.html
.\" A Memory Allocator - by Doug Lea