include/pub_tool_errormgr.h

   1 /*--------------------------------------------------------------------*/
   2 /*--- ErrorMgr: management of errors and suppressions.             ---*/
   3 /*---                                          pub_tool_errormgr.h ---*/
   4 /*--------------------------------------------------------------------*/
   5
   6 /*
   7    This file is part of Valgrind, a dynamic binary instrumentation
   8    framework.
   9
  10    Copyright (C) 2000-2017 Julian Seward
  11       jseward@acm.org
  12
  13    This program is free software; you can redistribute it and/or
  14    modify it under the terms of the GNU General Public License as
  15    published by the Free Software Foundation; either version 2 of the
  16    License, or (at your option) any later version.
  17
  18    This program is distributed in the hope that it will be useful, but
  19    WITHOUT ANY WARRANTY; without even the implied warranty of
  20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21    General Public License for more details.
  22
  23    You should have received a copy of the GNU General Public License
  24    along with this program; if not, see <http://www.gnu.org/licenses/>.
  25
  26    The GNU General Public License is contained in the file COPYING.
  27 */
  28
  29 #ifndef __PUB_TOOL_ERRORMGR_H
  30 #define __PUB_TOOL_ERRORMGR_H
  31
  32 #include "pub_tool_execontext.h"
  33
  34 /* ------------------------------------------------------------------ */
  35 /* Error records contain enough info to generate an error report.  The idea
  36    is that (typically) the same few points in the program generate thousands
  37    of errors, and we don't want to spew out a fresh error message for each
  38    one.  Instead, we use these structures to common up duplicates.
  39 */
  40
  41 typedef
  42    Int         /* Do not make this unsigned! */
  43    ErrorKind;
  44
  45 /* The tool-relevant parts of an Error are:
  46      kind:   what kind of error; must be in the range (0..)
  47      addr:   use is optional.  0 by default.
  48      string: use is optional.  NULL by default.
  49      extra:  use is optional.  NULL by default.  void* so it's extensible.
  50 */
  51 typedef
  52    struct _Error
  53    Error;
  54
  55 /* Useful in VG_(tdict).tool_error_matches_suppression(),
  56  * VG_(tdict).tool_pp_Error(), etc */
  57 ExeContext*  VG_(get_error_where)   ( const Error* err );
  58 ErrorKind    VG_(get_error_kind)    ( const Error* err );
  59 Addr         VG_(get_error_address) ( const Error* err );
  60 const HChar* VG_(get_error_string)  ( const Error* err );
  61 void*        VG_(get_error_extra)   ( const Error* err );
  62
  63 /* Call this when an error occurs.  It will be recorded if it hasn't been
  64    seen before.  If it has, the existing error record will have its count
  65    incremented.
  66
  67    'tid' can be found as for VG_(record_ExeContext)().  The `s' string
  68    and `extra' field can be stack-allocated;  they will be copied by the core
  69    if needed (but it won't be copied if it's NULL).
  70    Note that `ekind' and `s' are also used to generate a suppression.
  71    `s' should therefore not contain data depending on the specific
  72    execution (such as addresses, values) but should rather contain
  73    e.g. a system call parameter symbolic name.
  74    `extra' is also (optionally) used for generating a suppression
  75    (see pub_tool_tooliface.h print_extra_suppression_info).
  76
  77    If no 'a', 's' or 'extra' of interest needs to be recorded, just use
  78    NULL for them.
  79
  80    ATTENTION: 's' should not contain information that is (too) specific
  81    to an instance of an error.  For example, 's' can clearly not contain
  82    an address, as otherwise no way the user can build a suppression entry
  83    matching such a variable error extra string.  It should preferrably not
  84    contain offset or array indexes, for similar reason.
  85    In other words, 's' should be NULL or should be a static string.
  86    Finally, if you change the string 's' from one release to another
  87    for the same error, you will introduce backward incompatible changes
  88    with the suppression files produced for previous releases.
  89    So, don't do that ! */
  90 extern void VG_(maybe_record_error) ( ThreadId tid, ErrorKind ekind,
  91                                       Addr a, const HChar* s, void* extra );
  92
  93 /* Similar to VG_(maybe_record_error)(), except this one doesn't record the
  94    error -- useful for errors that can only happen once.  The errors can be
  95    suppressed, though.  Return value is True if it was suppressed.
  96    'print_error' dictates whether to print the error, which is a bit of a
  97    hack that's useful sometimes if you just want to know if the error would
  98    be suppressed without possibly printing it.  'count_error' dictates
  99    whether to add the error in the error total count (another mild hack).
 100
 101    ATTENTION: read the 'ATTENTION' above for VG_(maybe_record_error) ! */
 102 extern Bool VG_(unique_error) ( ThreadId tid, ErrorKind ekind,
 103                                 Addr a, const HChar* s, void* extra,
 104                                 ExeContext* where, Bool print_error,
 105                                 Bool allow_GDB_attach, Bool count_error );
 106
 107 /* Gets from fd (an opened suppression file) a non-blank, non-comment
 108    line containing suppression extra information (e.g. the syscall
 109    line for the Param memcheck suppression kind.  bufpp is a pointer
 110    to a buffer that must be allocated with VG_(malloc);
 111    nBufp is a pointer to size_t holding its size; if the buffer is too
 112    small for the line, it will be realloc'd until big enough (updating
 113    *bufpp and *nBufp in the process).  (It will bomb out if the size
 114    gets ridiculous).  Skips leading spaces on the line.  Increments
 115    *lineno with the number of lines read. Returns True if no extra
 116    information line could be read. */
 117 extern Bool VG_(get_line) ( Int fd, HChar** bufpp, SizeT* nBufp, Int* lineno );
 118
 119
 120 /* ------------------------------------------------------------------ */
 121 /* Suppressions describe errors which we want to suppress, ie, not
 122    show the user, usually because it is caused by a problem in a library
 123    which we can't fix, replace or work around.  Suppressions are read from
 124    a file at startup time.  This gives flexibility so that new
 125    suppressions can be added to the file as and when needed.
 126 */
 127 typedef
 128    Int         /* Do not make this unsigned! */
 129    SuppKind;
 130
 131 /* The tool-relevant parts of a suppression are:
 132      kind:   what kind of suppression; must be in the range (0..)
 133      string: use is optional.  NULL by default.
 134      extra:  use is optional.  NULL by default.  void* so it's extensible.
 135 */
 136 typedef
 137    struct _Supp
 138    Supp;
 139
 140 /* Useful in VG_(tdict).tool_error_matches_suppression() */
 141 SuppKind VG_(get_supp_kind)   ( const Supp* su );
 142 HChar*   VG_(get_supp_string) ( const Supp* su );
 143 void*    VG_(get_supp_extra)  ( const Supp* su );
 144
 145 /* Must be used in VG_(recognised_suppression)() */
 146 void VG_(set_supp_kind)   ( Supp* su, SuppKind suppkind );
 147 /* May be used in VG_(read_extra_suppression_info)() */
 148 void VG_(set_supp_string) ( Supp* su, HChar* string );
 149 void VG_(set_supp_extra)  ( Supp* su, void* extra );
 150
 151
 152 #endif   // __PUB_TOOL_ERRORMGR_H
 153
 154 /*--------------------------------------------------------------------*/
 155 /*--- end                                                          ---*/
 156 /*--------------------------------------------------------------------*/