Home | History | Annotate | Line # | Download | only in dist 
      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)
    118