external/bsd/kyua-testers/dist/error.h

   1 // Copyright 2012 Google Inc.
   2 // All rights reserved.
   3 //
   4 // Redistribution and use in source and binary forms, with or without
   5 // modification, are permitted provided that the following conditions are
   6 // met:
   7 //
   8 // * Redistributions of source code must retain the above copyright
   9 //   notice, this list of conditions and the following disclaimer.
  10 // * Redistributions in binary form must reproduce the above copyright
  11 //   notice, this list of conditions and the following disclaimer in the
  12 //   documentation and/or other materials provided with the distribution.
  13 // * Neither the name of Google Inc. nor the names of its contributors
  14 //   may be used to endorse or promote products derived from this software
  15 //   without specific prior written permission.
  16 //
  17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 /// \file error.h
  30 /// High-level representation of error conditions.
  31 ///
  32 /// The error module provides a mechanism to represent error conditions in an
  33 /// efficient manner.  In the case of a successful operation, an error is
  34 /// internally represented as a NULL pointer and thus has no overhead.  In the
  35 /// case of an actual error, the representation is more complex and costly than
  36 /// a traditional libc error number, but is also more verbose.  Because errors
  37 /// are not (or should not be!) in the critical path, this is not a concern.
  38
  39 #if !defined(KYUA_ERROR_H)
  40 #define KYUA_ERROR_H
  41
  42 #include "error_fwd.h"
  43
  44 #include <stdbool.h>
  45 #include <stddef.h>
  46 #include <stdio.h>
  47
  48 #include "defs.h"
  49
  50
  51 /// Type of the per-error formatting function.
  52 ///
  53 /// These functions take three arguments: the error to be formatted, a pointer
  54 /// to the output buffer and the size of the output buffer.  The return value
  55 /// indicates how many bytes were written to the output buffer, or a negative
  56 /// value in case of an error.
  57 typedef int (*kyua_error_format_callback)(
  58     struct kyua_error* const, char* const, const size_t);
  59
  60
  61 /// Representation of an error.
  62 struct kyua_error {
  63     /// Whether the error object has to be released or not.
  64     ///
  65     /// Sometimes (the oom error), a kyua_error_t object may point to a
  66     /// statically allocated error.  Such object cannot be freed.
  67     bool needs_free;
  68
  69     /// Name of the type.
  70     const char* type_name;
  71
  72     /// Opaquet error-specific data.
  73     void* data;
  74
  75     /// Method to generate a textual representation of the error.
  76     kyua_error_format_callback format_callback;
  77 };
  78
  79
  80 kyua_error_t kyua_error_new(const char*, void*, size_t,
  81                             kyua_error_format_callback);
  82 void kyua_error_free(kyua_error_t);
  83 kyua_error_t kyua_error_subsume(kyua_error_t, kyua_error_t);
  84
  85 kyua_error_t kyua_error_ok(void);
  86 bool kyua_error_is_set(const kyua_error_t);
  87 bool kyua_error_is_type(const kyua_error_t, const char*);
  88
  89 const void* kyua_error_data(const kyua_error_t);
  90 int kyua_error_format(const kyua_error_t, char* const, size_t);
  91 void kyua_error_err(const int, const kyua_error_t, const char*, ...)
  92     KYUA_DEFS_NORETURN KYUA_DEFS_FORMAT_PRINTF(3, 4);
  93 void kyua_error_fprintf(FILE*, const kyua_error_t, const char*, ...);
  94 void kyua_error_warn(const kyua_error_t, const char*, ...);
  95
  96
  97 extern const char* const kyua_generic_error_type;
  98 kyua_error_t kyua_generic_error_new(const char* , ...)
  99     KYUA_DEFS_FORMAT_PRINTF(1, 2);
 100
 101
 102 extern const char* const kyua_libc_error_type;
 103 kyua_error_t kyua_libc_error_new(int, const char* , ...)
 104     KYUA_DEFS_FORMAT_PRINTF(2, 3);
 105 int kyua_libc_error_errno(const kyua_error_t);
 106
 107
 108 extern const char* const kyua_oom_error_type;
 109 kyua_error_t kyua_oom_error_new(void);
 110
 111
 112 extern const char* const kyua_usage_error_type;
 113 kyua_error_t kyua_usage_error_new(const char* , ...)
 114     KYUA_DEFS_FORMAT_PRINTF(1, 2);
 115
 116
 117 #endif  // !defined(KYUA_ERROR_H)