X-Git-Url: https://git.ozlabs.org/?p=ccan;a=blobdiff_plain;f=ccan%2Fcompiler%2Fcompiler.h;h=7adcc8ca1a4ea521cb11069d3dce4dff062ecb14;hp=3601749003894974267a59e515db9a1cce6c8235;hb=d40331c745a6e4a56a3ea210ef9e1e264f7e6e5a;hpb=89f1301ed2b65cdb4730bb28c42428873a69faec

diff --git a/ccan/compiler/compiler.h b/ccan/compiler/compiler.h
index 36017490..7adcc8ca 100644
--- a/ccan/compiler/compiler.h
+++ b/ccan/compiler/compiler.h
@@ -4,32 +4,33 @@
 
 #if HAVE_ATTRIBUTE_COLD
 /**
- * UNLIKELY_FUNCTION_ATTRIBUTE - a function is unlikely to be called.
+ * COLD_ATTRIBUTE - a function is unlikely to be called.
  *
  * Used to mark an unlikely code path and optimize appropriately.
  * It is usually used on logging or error routines.
  *
  * Example:
- *	void UNLIKELY_FUNCTION_ATTRIBUTE moan(const char *reason)
- *	{
- *		fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
- *	}
+ * static void COLD_ATTRIBUTE moan(const char *reason)
+ * {
+ *	fprintf(stderr, "Error: %s (%s)\n", reason, strerror(errno));
+ * }
  */
-#define UNLIKELY_FUNCTION_ATTRIBUTE __attribute__((cold))
+#define COLD_ATTRIBUTE __attribute__((cold))
 #else
-#define UNLIKELY_FUNCTION_ATTRIBUTE
+#define COLD_ATTRIBUTE
 #endif
 
 #if HAVE_ATTRIBUTE_PRINTF
 /**
  * PRINTF_ATTRIBUTE - a function takes printf-style arguments
- * nfmt: the 1-based number of the function's format argument.
- * narg: the 1-based number of the function's first variable argument.
+ * @nfmt: the 1-based number of the function's format argument.
+ * @narg: the 1-based number of the function's first variable argument.
  *
  * This allows the compiler to check your parameters as it does for printf().
  *
  * Example:
- *	void PRINTF_ATTRIBUTE(2,3) my_printf(char *prefix, char *format, ...);
+ * void PRINTF_ATTRIBUTE(2,3) my_printf(const char *prefix,
+ *					const char *fmt, ...);
  */
 #define PRINTF_ATTRIBUTE(nfmt, narg) \
 	__attribute__((format(__printf__, nfmt, narg)))
@@ -58,18 +59,14 @@
  * the compiler that if it is unused it need not emit it into the source code.
  *
  * Example:
- *	// With some config options, this is unnecessary.
- *	static UNNEEDED_ATTRIBUTE int counter;
- *	...
- *		#ifdef DEBUG
- *		counter++;
- *		#endif
- *	...
- *	// With some config options, this is unnecessary.
- *	static UNNEEDED_ATTRIBUTE int add_to_counter(int add)
- *	{
- *		counter += add;
- *	}
+ * // With some preprocessor options, this is unnecessary.
+ * static UNNEEDED_ATTRIBUTE int counter;
+ *
+ * // With some preprocessor options, this is unnecessary.
+ * static UNNEEDED_ATTRIBUTE void add_to_counter(int add)
+ * {
+ *	counter += add;
+ * }
  */
 #define UNNEEDED_ATTRIBUTE __attribute__((unused))
 
@@ -117,7 +114,7 @@
  *	const char *greek_name(enum greek greek);
  *
  *	// Inline version.
- *	static inline _greek_name(enum greek greek)
+ *	static inline char *_greek_name(enum greek greek)
  *	{
  *		switch (greek) {
  *		case ALPHA: return "alpha";
@@ -139,4 +136,23 @@
 /* If we don't know, assume it's not. */
 #define IS_COMPILE_CONSTANT(expr) 0
 #endif
+
+#if HAVE_WARN_UNUSED_RESULT
+/**
+ * WARN_UNUSED_RESULT - warn if a function return value is unused.
+ *
+ * Used to mark a function where it is extremely unlikely that the caller
+ * can ignore the result, eg realloc().
+ *
+ * Example:
+ * // buf param may be freed by this; need return value!
+ * static char *WARN_UNUSED_RESULT enlarge(const char *buf, unsigned *size)
+ * {
+ *	return realloc(buf, (*size) *= 2);
+ * }
+ */
+#define WARN_UNUSED_RESULT __attribute__((warn_unused_result))
+#else
+#define WARN_UNUSED_RESULT
+#endif
 #endif /* CCAN_COMPILER_H */