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-2013 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, write to the Free Software 25 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 26 02111-1307, USA. 27 28 The GNU General Public License is contained in the file COPYING. 29 */ 30 31 #ifndef __PUB_TOOL_ERRORMGR_H 32 #define __PUB_TOOL_ERRORMGR_H 33 34 #include "pub_tool_execontext.h" 35 36 /* ------------------------------------------------------------------ */ 37 /* Error records contain enough info to generate an error report. The idea 38 is that (typically) the same few points in the program generate thousands 39 of errors, and we don't want to spew out a fresh error message for each 40 one. Instead, we use these structures to common up duplicates. 41 */ 42 43 typedef 44 Int /* Do not make this unsigned! */ 45 ErrorKind; 46 47 /* The tool-relevant parts of an Error are: 48 kind: what kind of error; must be in the range (0..) 49 addr: use is optional. 0 by default. 50 string: use is optional. NULL by default. 51 extra: use is optional. NULL by default. void* so it's extensible. 52 */ 53 typedef 54 struct _Error 55 Error; 56 57 /* Useful in VG_(tdict).tool_error_matches_suppression(), 58 * VG_(tdict).tool_pp_Error(), etc */ 59 ExeContext* VG_(get_error_where) ( Error* err ); 60 ErrorKind VG_(get_error_kind) ( Error* err ); 61 Addr VG_(get_error_address) ( Error* err ); 62 const HChar* VG_(get_error_string) ( Error* err ); 63 void* VG_(get_error_extra) ( Error* err ); 64 65 /* Call this when an error occurs. It will be recorded if it hasn't been 66 seen before. If it has, the existing error record will have its count 67 incremented. 68 69 'tid' can be found as for VG_(record_ExeContext)(). The `extra' field can 70 be stack-allocated; it will be copied by the core if needed (but it 71 won't be copied if it's NULL). 72 73 If no 'a', 's' or 'extra' of interest needs to be recorded, just use 74 NULL for them. */ 75 extern void VG_(maybe_record_error) ( ThreadId tid, ErrorKind ekind, 76 Addr a, const HChar* s, void* extra ); 77 78 /* Similar to VG_(maybe_record_error)(), except this one doesn't record the 79 error -- useful for errors that can only happen once. The errors can be 80 suppressed, though. Return value is True if it was suppressed. 81 'print_error' dictates whether to print the error, which is a bit of a 82 hack that's useful sometimes if you just want to know if the error would 83 be suppressed without possibly printing it. 'count_error' dictates 84 whether to add the error in the error total count (another mild hack). */ 85 extern Bool VG_(unique_error) ( ThreadId tid, ErrorKind ekind, 86 Addr a, const HChar* s, void* extra, 87 ExeContext* where, Bool print_error, 88 Bool allow_GDB_attach, Bool count_error ); 89 90 /* Gets from fd (an opened suppression file) a non-blank, non-comment 91 line containing suppression extra information (e.g. the syscall 92 line for the Param memcheck suppression kind. bufpp is a pointer 93 to a pointer to a buffer that must be allocated with VG_(malloc); 94 nBufp is a pointer to size_t holding its size; if the buffer is too 95 small for the line, it will be realloc'd until big enough (updating 96 *bufpp and *nBufp in the process). (It will bomb out if the size 97 gets ridiculous). Skips leading spaces on the line. Increments 98 lineno with the number of lines read if lineno is non-NULL. Returns 99 True if no extra information line could be read. */ 100 extern Bool VG_(get_line) ( Int fd, HChar** bufpp, SizeT* nBufp, Int* lineno ); 101 102 103 /* ------------------------------------------------------------------ */ 104 /* Suppressions describe errors which we want to suppress, ie, not 105 show the user, usually because it is caused by a problem in a library 106 which we can't fix, replace or work around. Suppressions are read from 107 a file at startup time. This gives flexibility so that new 108 suppressions can be added to the file as and when needed. 109 */ 110 typedef 111 Int /* Do not make this unsigned! */ 112 SuppKind; 113 114 /* The tool-relevant parts of a suppression are: 115 kind: what kind of suppression; must be in the range (0..) 116 string: use is optional. NULL by default. 117 extra: use is optional. NULL by default. void* so it's extensible. 118 */ 119 typedef 120 struct _Supp 121 Supp; 122 123 /* Useful in VG_(tdict).tool_error_matches_suppression() */ 124 SuppKind VG_(get_supp_kind) ( Supp* su ); 125 HChar* VG_(get_supp_string) ( Supp* su ); 126 void* VG_(get_supp_extra) ( Supp* su ); 127 128 /* Must be used in VG_(recognised_suppression)() */ 129 void VG_(set_supp_kind) ( Supp* su, SuppKind suppkind ); 130 /* May be used in VG_(read_extra_suppression_info)() */ 131 void VG_(set_supp_string) ( Supp* su, HChar* string ); 132 void VG_(set_supp_extra) ( Supp* su, void* extra ); 133 134 135 #endif // __PUB_TOOL_ERRORMGR_H 136 137 /*--------------------------------------------------------------------*/ 138 /*--- end ---*/ 139 /*--------------------------------------------------------------------*/ 140