add slibc-error.h

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 233 insertions, 0 deletions

diff --git a/include/slibc-error.h b/include/slibc-error.h
new file mode 100644
index 0000000..c84faad
--- /dev/null
+++ b/include/slibc-error.h
@@ -0,0 +1,233 @@
+/**
+ * slibc — Yet another C library
+ * Copyright © 2015  Mattias Andrée (maandree@member.fsf.org)
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#ifndef _SLIBC_ERROR_H
+#define _SLIBC_ERROR_H
+#ifndef _PORTABLE_SOURCE
+#include <slibc/version.h>
+
+
+#include <slibc/features.h>
+#include <stdarg.h>
+#include <errno.h>
+
+
+
+/**
+ * Store the current line, so we know which line failed, when
+ * `PRINT_CUSTOM_FAILURE`, `PRINT_FAILURE` or `slibc_perror`
+ * is called. This expression will be evaluated.
+ * 
+ * Example usage:
+ * ```
+ * int my_function(void)
+ * {
+ *   size_t n;
+ *   void* array;
+ *   ...
+ *   if (FAILABLE_CALL(array = malloc(n)) == NULL)
+ *     goto fail;
+ *   ...
+ *   return 0;
+ *   
+ *  fail:
+ *   PRINT_FAILURE(NULL);
+ *   ...
+ *   return errno = 0, -1;
+ * }
+ * ```
+ * 
+ * A more scalable example:
+ * ```
+ * #define fail_if (call_and_check)  \
+ *   do { if (FAILABLE_CALL(call_and_check)) goto fail; } while (0)
+ * // `try` or simply `t` may be even better.
+ * 
+ * #define fail_unless (call_and_check)  fail_if(!(call_and_check))
+ * // `f` may be even better.
+ * 
+ * int my_function(void)
+ * {
+ *   size_t n;
+ *   void* array;
+ *   ...
+ *   fail_if (!(array = malloc(n)));
+ *   // or perhaps, fail_unless (array = malloc(n));
+ *   ...
+ *   return 0;
+ *   
+ *  fail:
+ *   PRINT_FAILURE(NULL);
+ *   ...
+ *   return errno = 0, -1;
+ * }
+ * ```
+ * 
+ * This is a slibc extension.
+ */
+#define FAILABLE_CALL(expression)  \
+  ({ typeof(expression) __slibc_r = (expression); *__slibc_error_line() = __LINE__; __slibc_r; })
+
+/**
+ * Check whether an error occurred. If an error occurred,
+ * stored the line, for `PRINT_CUSTOM_FAILURE`, `PRINT_FAILURE`
+ * or `slibc_perror`, where the error occurred.
+ * 
+ * Example usage:
+ * ```
+ * int my_function(void)
+ * {
+ *   char* buf;
+ *   size_t bufsize;
+ *   ssize_t r;
+ *   int fd;
+ *   ...
+ *   for (;;)
+ *     {
+ *       r = read(fd, buf, bufsize);
+ *       if (FAILURE_CHECK(r < 0, 1))
+ *         {
+ *           if (errno != EINTR) // Possibly FAILURE_CHECK(errno != EINTR, 3) here instead.
+ *             goto fail;
+ *           continue;
+ *         }
+ *       ...
+ *     }
+ *   ...
+ *   return 0;
+ *   
+ *  fail:
+ *   PRINT_FAILURE(NULL);
+ *   ...
+ *   return errno = 0, -1;
+ * }
+ * ```
+ * 
+ * This is a slibc extension.
+ * 
+ * @param   condition  Should evaluate to non-zero on and only on error.
+ * @param   offset     The number of lines above the current line
+ *                     that was the line that failed, if `condition`
+ *                     evaluates to non-zero.
+ * @return             1 if `condition` evaluates to non-zero, 0 otherwise.
+ */
+#define FAILURE_CHECK(condition, offset)  \
+  ((condition) ? (*__slibc_error_line() = (__LINE__ - (offset)), 1) : 0)
+
+/**
+ * Print an error message describing the error, and where the error
+ * happened. Optionally with detailed description of the action that
+ * failed.
+ * 
+ * This function must be called in the same file and function as the
+ * the expansion of `FAILABLE_CALL` or `FAILURE_CHECK`. It is recommended
+ * that this is done all the way down the call-stack to `main'. This is
+ * however problematic (although it is possible) if you do not want the
+ * process to exit.
+ * 
+ * Example of recursion:
+ * ```
+ * static int b(void)
+ * {
+ *   if (FAILABLE_CALL(some_function()) < 0) goto fail;
+ *   return 0; fail: PRINT_FAILURE(NULL); return -1;
+ * }
+ * static int a(void)
+ * {
+ *   if (FAILABLE_CALL(b()) < 0) goto fail;
+ *   return 0; fail: PRINT_FAILURE(NULL); return -1;
+ * }
+ * int main(void)
+ * {
+ *   if (FAILABLE_CALL(a()) < 0) goto fail;
+ *   return 0; fail: PRINT_FAILURE(NULL); return 1;
+ * }
+ * ```
+ * 
+ * This function will set `errno` to zero. If you have statements
+ * after the call to this function that may modify `errno`, be sure
+ * to set `errno` to zero before returning. A good way to do this
+ * is to have the return statement look like `return errno = 0, -1`.
+ * 
+ * This is a slibc extension.
+ * 
+ * @param  ...  Formatting-string followed by formatting-arguments used
+ *              to describe what action failed. If the first argument is
+ *              `NULL`, this is not printed and only the location of the
+ *              error and `errno` is used to describe the error.
+ */
+#define PRINT_FAILURE(...)  \
+  (PRINT_CUSTOM_FAILURE(errno, NULL, __VA_ARGS__))
+
+/**
+ * Variant of `PRINT_FAILURE` that allows another function than `strerror`
+ * to be used to get a textual description of the error code.
+ * (This function will not set `errno` to zero unless it is the first argument.)
+ * 
+ * Example: `PRINT_CUSTOM_FAILURE(r, gai_strerror(r), _("fail to connect to server: %s"), host)`
+ * 
+ * This is a slibc extension.
+ * 
+ * @param  error_code    The error code, must be a modifiable lvalue, as it will be
+ *                       modified to zero to indicate that the error string has
+ *                       already been printed. Thus, on the original error location
+ *                       this value must not be zero.
+ * @param  error_string  Textual representation of the error. If `errno` indicates
+ *                       the error, this should usually be `strerror(errno)`.
+ * @param  ...           Formatting-string followed by formatting-arguments used
+ *                       to describe what action failed. If the first argument is
+ *                       `NULL`, this is not printed and only the location of the
+ *                       error and `error_string` is used to describe the error.
+ */
+#define PRINT_CUSTOM_FAILURE(error_code, error_string, ...)  \
+  (slibc_perror(NULL, __FILE__, *__slibc_error_line(), __func__, &(error_code), error_string, __VA_ARGS__))
+
+/**
+ * Helper function to keep track of the line of origin, in a
+ * thread-safe manner, without requiring new revisions of C.
+ */
+int* __slibc_error_line(void) __GCC_ONLY(__attribute__((__const__))); /* TODO not implemented */
+
+/**
+ * Print a description of an error, and where the error occurred.
+ * This function is capable of printed the full call-stack.
+ * 
+ * It is not recommended to used this function direction.
+ * Use the macros in <slibc-error.h> instead.
+ * 
+ * This is a slibc extension.
+ * 
+ * @param  progname      The name of the program, `NULL` to use `program_invocation_name`.
+ * @param  filename      The source code file where the error occurred.
+ * @param  linenum       The line in the source code where the error occurred.
+ * @param  function      The function in the source code where the error occurred.
+ * @param  error_code    Pointer the variable that stores the error code, will zeroed.
+ * @param  error_string  Textual description of the error code, `NULL` if `strerror` should be used.
+ *                       This parameter is unused if `error_code` is zero.
+ * @param  format        Formatting-string for a description of the action that failed. `NULL` if
+ *                       no description other than the location and `error_string` should be printed.
+ * @param  ...           Formatting-arguments for `format`.
+ */
+void slibc_perror(const char* progname, const char* filename, int linenum, const char* function,
+		  int* error_code, const char* error_string, const char* format, ...)
+  __GCC_ONLY(__attribute__((nonnull(2, 4), format(printf, 7, 8))));
+
+
+
+#endif
+#endif
+