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
43typedef
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*/
53typedef
54   struct _Error
55   Error;
56
57/* Useful in VG_(tdict).tool_error_matches_suppression(),
58 * VG_(tdict).tool_pp_Error(), etc */
59ExeContext*  VG_(get_error_where)   ( Error* err );
60ErrorKind    VG_(get_error_kind)    ( Error* err );
61Addr         VG_(get_error_address) ( Error* err );
62const HChar* VG_(get_error_string)  ( Error* err );
63void*        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.  */
75extern 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). */
85extern 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. */
100extern 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*/
110typedef
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*/
119typedef
120   struct _Supp
121   Supp;
122
123/* Useful in VG_(tdict).tool_error_matches_suppression() */
124SuppKind VG_(get_supp_kind)   ( Supp* su );
125HChar*   VG_(get_supp_string) ( Supp* su );
126void*    VG_(get_supp_extra)  ( Supp* su );
127
128/* Must be used in VG_(recognised_suppression)() */
129void VG_(set_supp_kind)   ( Supp* su, SuppKind suppkind );
130/* May be used in VG_(read_extra_suppression_info)() */
131void VG_(set_supp_string) ( Supp* su, HChar* string );
132void VG_(set_supp_extra)  ( Supp* su, void* extra );
133
134
135#endif   // __PUB_TOOL_ERRORMGR_H
136
137/*--------------------------------------------------------------------*/
138/*--- end                                                          ---*/
139/*--------------------------------------------------------------------*/
140