From: Mark Wooding <mdw@distorted.org.uk>
Date: Thu, 22 Dec 2022 17:10:27 +0000 (+0000)
Subject: utils/macros.h: Add `MUST_CHECK', so return codes aren't ignored.
X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/commitdiff_plain/8c470f2a28273197fbf0939a7bceb3d0d0a6df7d

utils/macros.h: Add `MUST_CHECK', so return codes aren't ignored.
---

diff --git a/utils/macros.3 b/utils/macros.3
index f5dac97..d481a47 100644
--- a/utils/macros.3
+++ b/utils/macros.3
@@ -30,6 +30,7 @@ macros \- useful macros
 .\" @DEPRECATED
 .\" @EXECL_LIKE
 .\" @IGNORABLE
+.\" @MUST_CHECK
 .\" @NORETURN
 .\" @PRINTF_LIKE
 .\" @SCANF_LIKE
@@ -74,6 +75,7 @@ macros \- useful macros
 .BI "DEPRECATED(" msg ")"
 .BI "EXECL_LIKE(" ntrail ")"
 .BI "IGNORABLE"
+.BI "MUST_CHECK"
 .BI "NORETURN"
 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
@@ -193,6 +195,12 @@ need not be used.  This may muffle warnings about leaving the marked
 definition unused.
 .PP
 A function marked as
+.B MUST_CHECK
+returns an important value: a warning may be issued if a caller
+ignores the value.  The return type must not be
+.BR void .
+.PP
+A function marked as
 .B NORETURN
 must not return.  It must have return type
 .BR void .
diff --git a/utils/macros.h b/utils/macros.h
index 45420e2..70f535f 100644
--- a/utils/macros.h
+++ b/utils/macros.h
@@ -94,6 +94,10 @@
 #  define IGNORABLE __attribute__((__unused__))
 #endif
 
+#if GCC_VERSION_P(3, 4) || CLANG_VERSION_P(3, 3)
+#  define MUST_CHECK __attribute__((__warn_unused_result__))
+#endif
+
 #if GCC_VERSION_P(4, 5) || CLANG_VERSION_P(3, 3)
 #  define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
 #elif GCC_VERSION_P(3, 1)
@@ -223,6 +227,10 @@
 #  define IGNORABLE
 #endif
 
+#ifndef MUST_CHECK
+#  define MUST_CHECK
+#endif
+
 #ifndef GCC_WARNING
 #  define GCC_WARNING(warn)
 #endif