exception_handler.h

mozilla-central/toolkit/crashreporter/breakpad-client/windows/handler/exception_handler.h (file symbol)

Enable keyboard shortcuts

Source code

Revision control

Copy as Markdown

Other Tools

// Copyright (c) 2006, Google Inc.

// All rights reserved.

//

// Redistribution and use in source and binary forms, with or without

// modification, are permitted provided that the following conditions are

// met:

//

//     * Redistributions of source code must retain the above copyright

// notice, this list of conditions and the following disclaimer.

//     * Redistributions in binary form must reproduce the above

// copyright notice, this list of conditions and the following disclaimer

// in the documentation and/or other materials provided with the

// distribution.

//     * Neither the name of Google Inc. nor the names of its

// contributors may be used to endorse or promote products derived from

// this software without specific prior written permission.

//

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// ExceptionHandler can write a minidump file when an exception occurs,

// or when WriteMinidump() is called explicitly by your program.

//

// To have the exception handler write minidumps when an uncaught exception

// (crash) occurs, you should create an instance early in the execution

// of your program, and keep it around for the entire time you want to

// have crash handling active (typically, until shutdown).

//

// If you want to write minidumps without installing the exception handler,

// you can create an ExceptionHandler with install_handler set to false,

// then call WriteMinidump.  You can also use this technique if you want to

// use different minidump callbacks for different call sites.

//

// In either case, a callback function is called when a minidump is written,

// which receives the unqiue id of the minidump.  The caller can use this

// id to collect and write additional application state, and to launch an

// external crash-reporting application.

//

// It is important that creation and destruction of ExceptionHandler objects

// be nested cleanly, when using install_handler = true.

// Avoid the following pattern:

//   ExceptionHandler *e = new ExceptionHandler(...);

//   ExceptionHandler *f = new ExceptionHandler(...);

//   delete e;

// This will put the exception filter stack into an inconsistent state.

#ifndef CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__

#define CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__

#include <stdlib.h>

#include <windows.h>

#include <dbghelp.h>

#include <rpc.h>

#pragma warning(push)

// Disable exception handler warnings.

#pragma warning(disable:4530)

#include <list>

#include <string>

#include <vector>

#include "windows/common/minidump_callback.h"

#include "windows/common/ipc_protocol.h"

#include "windows/crash_generation/crash_generation_client.h"

#include "common/scoped_ptr.h"

#include "google_breakpad/common/minidump_format.h"

#ifdef MOZ_PHC

#include "PHC.h"

#else

namespace mozilla { namespace phc { class AddrInfo {}; } }

#endif

namespace google_breakpad {

using std::vector;

using std::wstring;

class ExceptionHandler {

 public:

  // The result value for the filter callback, see below.

  enum class FilterResult {

    HandleException,

    AbortWithoutMinidump,

    ContinueSearch

};

  // A callback function to run before Breakpad performs any substantial

  // processing of an exception.  A FilterCallback is called before writing

  // a minidump.  context is the parameter supplied by the user as

  // callback_context when the handler was created.  exinfo points to the

  // exception record, if any; assertion points to assertion information,

  // if any.

//

  // If a FilterCallback returns HandleException, Breakpad will attempt to

  // write a minidump.  If a FilterCallback returns ContinueSearch Breakpad

  // will immediately report the exception as unhandled without writing a

  // minidump, allowing another handler the opportunity to handle it.

  // If a FilterCallback returns AbortWithoutMinidump, Breakpad will report the

  // exception as handled but will not write a minidump, letting the process

  // terminate itself instead.

  typedef FilterResult (*FilterCallback)(void* context,

                                         EXCEPTION_POINTERS* exinfo,

                                         MDRawAssertionInfo* assertion);

  // A callback function to run after the minidump has been written.

  // minidump_id is a unique id for the dump, so the minidump

  // file is <dump_path>\<minidump_id>.dmp.  context is the parameter supplied

  // by the user as callback_context when the handler was created.  exinfo

  // points to the exception record, or NULL if no exception occurred.

  // succeeded indicates whether a minidump file was successfully written.

  // assertion points to information about an assertion if the handler was

  // invoked by an assertion.

//

  // If an exception occurred and the callback returns true, Breakpad will treat

  // the exception as fully-handled, suppressing any other handlers from being

  // notified of the exception.  If the callback returns false, Breakpad will

  // treat the exception as unhandled, and allow another handler to handle it.

  // If there are no other handlers, Breakpad will report the exception to the

  // system as unhandled, allowing a debugger or native crash dialog the

  // opportunity to handle the exception.  Most callback implementations

  // should normally return the value of |succeeded|, or when they wish to

  // not report an exception of handled, false.  Callbacks will rarely want to

  // return true directly (unless |succeeded| is true).

//

  // For out-of-process dump generation, dump path and minidump ID will always

  // be NULL. In case of out-of-process dump generation, the dump path and

  // minidump id are controlled by the server process and are not communicated

  // back to the crashing process.

  typedef bool (*MinidumpCallback)(const wchar_t* dump_path,

                                   const wchar_t* minidump_id,

                                   void* context,

                                   EXCEPTION_POINTERS* exinfo,

                                   MDRawAssertionInfo* assertion,

                                   const mozilla::phc::AddrInfo* addr_info,

                                   bool succeeded);

  // HandlerType specifies which types of handlers should be installed, if

  // any.  Use HANDLER_NONE for an ExceptionHandler that remains idle,

  // without catching any failures on its own.  This type of handler may

  // still be triggered by calling WriteMinidump.  Otherwise, use a

  // combination of the other HANDLER_ values, or HANDLER_ALL to install

  // all handlers.

  enum HandlerType {

    HANDLER_NONE = 0,

    HANDLER_EXCEPTION = 1 << 0,          // SetUnhandledExceptionFilter

    HANDLER_INVALID_PARAMETER = 1 << 1,  // _set_invalid_parameter_handler

    HANDLER_PURECALL = 1 << 2,           // _set_purecall_handler

    HANDLER_HEAP_CORRUPTION = 1 << 4,    // AddVectoredExceptionHandler

    HANDLER_ALL = HANDLER_EXCEPTION | HANDLER_INVALID_PARAMETER |

                  HANDLER_PURECALL | HANDLER_HEAP_CORRUPTION

};

  // Creates a new ExceptionHandler instance to handle writing minidumps.

  // Before writing a minidump, the optional filter callback will be called.

  // Its return value determines whether or not Breakpad should write a

  // minidump.  Minidump files will be written to dump_path, and the optional

  // callback is called after writing the dump file, as described above.

  // handler_types specifies the types of handlers that should be installed.

  ExceptionHandler(const wstring& dump_path,

                   FilterCallback filter,

                   MinidumpCallback callback,

                   void* callback_context,

                   int handler_types);

  // Creates a new ExceptionHandler instance that can attempt to perform

  // out-of-process dump generation if pipe_name is not NULL. If pipe_name is

  // NULL, or if out-of-process dump generation registration step fails,

  // in-process dump generation will be used. This also allows specifying

  // the dump type to generate.

  ExceptionHandler(const wstring& dump_path,

                   FilterCallback filter,

                   MinidumpCallback callback,

                   void* callback_context,

                   int handler_types,

                   MINIDUMP_TYPE dump_type,

                   const wchar_t* pipe_name,

                   const CustomClientInfo* custom_info);

  // As above, creates a new ExceptionHandler instance to perform

  // out-of-process dump generation if the given pipe_handle is not NULL.

  ExceptionHandler(const wstring& dump_path,

                   FilterCallback filter,

                   MinidumpCallback callback,

                   void* callback_context,

                   int handler_types,

                   MINIDUMP_TYPE dump_type,

                   HANDLE pipe_handle,

                   const CustomClientInfo* custom_info);

  // ExceptionHandler that ENSURES out-of-process dump generation.  Expects a

  // crash generation client that is already registered with a crash generation

  // server.  Takes ownership of the passed-in crash_generation_client.

//

  // Usage example:

  //   crash_generation_client = new CrashGenerationClient(..);

  //   if (crash_generation_client->Register()) {

  //     // Registration with the crash generation server succeeded.

  //     // Out-of-process dump generation is guaranteed.

  //     g_handler = new ExceptionHandler(.., crash_generation_client, ..);

  //     return true;

  //   }

  ExceptionHandler(const wstring& dump_path,

                   FilterCallback filter,

                   MinidumpCallback callback,

                   void* callback_context,

                   int handler_types,

                   CrashGenerationClient* crash_generation_client);

  ~ExceptionHandler();

  // Get and set the minidump path.

  wstring dump_path() const { return dump_path_; }

  void set_dump_path(const wstring &dump_path) {

    dump_path_ = dump_path;

    dump_path_c_ = dump_path_.c_str();

    UpdateNextID();  // Necessary to put dump_path_ in next_minidump_path_.

  // Requests that a previously reported crash be uploaded.

  bool RequestUpload(DWORD crash_id);

  // Writes a minidump immediately.  This can be used to capture the

  // execution state independently of a crash.  Returns true on success.

  bool WriteMinidump();

  // Writes a minidump immediately, with the user-supplied exception

  // information.

  bool WriteMinidumpForException(EXCEPTION_POINTERS* exinfo);

  // Convenience form of WriteMinidump which does not require an

  // ExceptionHandler instance.

  static bool WriteMinidump(const wstring &dump_path,

                            MinidumpCallback callback, void* callback_context,

                            MINIDUMP_TYPE dump_type = MiniDumpNormal);

  // Write a minidump of |child| immediately.  This can be used to

  // capture the execution state of |child| independently of a crash.

  // Pass a meaningful |child_blamed_thread| to make that thread in

  // the child process the one from which a crash signature is

  // extracted.

  static bool WriteMinidumpForChild(HANDLE child,

                                    DWORD child_blamed_thread,

                                    const wstring& dump_path,

                                    MinidumpCallback callback,

                                    void* callback_context,

                                    MINIDUMP_TYPE dump_type = MiniDumpNormal);

  // Get the thread ID of the thread requesting the dump (either the exception

  // thread or any other thread that called WriteMinidump directly).  This

  // may be useful if you want to include additional thread state in your

  // dumps.

  DWORD get_requesting_thread_id() const { return requesting_thread_id_; }

  // Controls behavior of EXCEPTION_BREAKPOINT and EXCEPTION_SINGLE_STEP.

  bool get_handle_debug_exceptions() const { return handle_debug_exceptions_; }

  void set_handle_debug_exceptions(bool handle_debug_exceptions) {

    handle_debug_exceptions_ = handle_debug_exceptions;

  // Controls behavior of EXCEPTION_INVALID_HANDLE.

  bool get_consume_invalid_handle_exceptions() const {

    return consume_invalid_handle_exceptions_;

  void set_consume_invalid_handle_exceptions(

      bool consume_invalid_handle_exceptions) {

    consume_invalid_handle_exceptions_ = consume_invalid_handle_exceptions;

  // Returns whether out-of-process dump generation is used or not.

  bool IsOutOfProcess() const { return crash_generation_client_.get() != NULL; }

  // Calling RegisterAppMemory(p, len) causes len bytes starting

  // at address p to be copied to the minidump when a crash happens.

  void RegisterAppMemory(void* ptr, size_t length);

  void UnregisterAppMemory(void* ptr);

  // Calling set_include_context_heap(true) causes heap regions to be included

  // in the minidump when a crash happens. The heap regions are from the

  // register values of the crashing context.

  void set_include_context_heap(bool enabled);

 private:

  friend class AutoExceptionHandler;

  // Initializes the instance with given values.

  void Initialize(const wstring& dump_path,

                  FilterCallback filter,

                  MinidumpCallback callback,

                  void* callback_context,

                  int handler_types,

                  MINIDUMP_TYPE dump_type,

                  const wchar_t* pipe_name,

                  HANDLE pipe_handle,

                  CrashGenerationClient* crash_generation_client,

                  const CustomClientInfo* custom_info);

  // Function pointer type for MiniDumpWriteDump, which is looked up

  // dynamically.

  typedef BOOL (WINAPI *MiniDumpWriteDump_type)(

      HANDLE hProcess,

      DWORD dwPid,

      HANDLE hFile,

      MINIDUMP_TYPE DumpType,

      CONST PMINIDUMP_EXCEPTION_INFORMATION ExceptionParam,

      CONST PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam,

      CONST PMINIDUMP_CALLBACK_INFORMATION CallbackParam);

  // Function pointer type for UuidCreate, which is looked up dynamically.

  typedef RPC_STATUS (RPC_ENTRY *UuidCreate_type)(UUID* Uuid);

  // Runs the main loop for the exception handler thread.

  static DWORD WINAPI ExceptionHandlerThreadMain(void* lpParameter);

  // Called on the exception thread when an unhandled exception occurs.

  // Signals the exception handler thread to handle the exception.

  static LONG WINAPI HandleException(EXCEPTION_POINTERS* exinfo);

#if _MSC_VER >= 1400  // MSVC 2005/8

  // This function will be called by some CRT functions when they detect

  // that they were passed an invalid parameter.  Note that in _DEBUG builds,

  // the CRT may display an assertion dialog before calling this function,

  // and the function will not be called unless the assertion dialog is

  // dismissed by clicking "Ignore."

  static void HandleInvalidParameter(const wchar_t* expression,

                                     const wchar_t* function,

                                     const wchar_t* file,

                                     unsigned int line,

                                     uintptr_t reserved);

#endif  // _MSC_VER >= 1400

  // This function will be called by the CRT when a pure virtual

  // function is called.

  static void HandlePureVirtualCall();

  // This function will be called by the vectored exception handler and will

  // generate a minidump only for exceptions of type STATUS_HEAP_CORRUPTION.

  static LONG WINAPI HandleHeapCorruption(EXCEPTION_POINTERS* exinfo);

  // This is called on the exception thread or on another thread that

  // the user wishes to produce a dump from.  It calls

  // WriteMinidumpWithException on the handler thread, avoiding stack

  // overflows and inconsistent dumps due to writing the dump from

  // the exception thread.  If the dump is requested as a result of an

  // exception, exinfo contains exception information, otherwise, it

  // is NULL.  If the dump is requested as a result of an assertion

  // (such as an invalid parameter being passed to a CRT function),

  // assertion contains data about the assertion, otherwise, it is NULL.

  bool WriteMinidumpOnHandlerThread(EXCEPTION_POINTERS* exinfo,

                                    MDRawAssertionInfo* assertion);

  // The return value for WriteMinidumpWithException(), see below.

  enum class MinidumpResult {

    Success,

    Failure,

    Ignored

};

  // This function is called on the handler thread.  It calls into

  // WriteMinidumpWithExceptionForProcess() with a handle to the

  // current process.  requesting_thread_id is the ID of the thread

  // that requested the dump.  If the dump is requested as a result of

  // an exception, exinfo contains exception information, otherwise,

  // it is NULL. It will return Success in case the minidump has been written

  // successfully, Failure if we couldn't write out the minidump because of an

  // error and Ignored if we didn't even try to write the minidump because the

  // filter callback indicated that we should ignore this exception and abort.

  // The latter condition is only relevent for a top-level exception handler,

  // other callers should equate it to a failure.

  MinidumpResult WriteMinidumpWithException(DWORD requesting_thread_id,

                                            EXCEPTION_POINTERS* exinfo,

                                            MDRawAssertionInfo* assertion);

  // This function does the actual writing of a minidump.  It is

  // called on the handler thread.  requesting_thread_id is the ID of

  // the thread that requested the dump, if that information is

  // meaningful.  If the dump is requested as a result of an

  // exception, exinfo contains exception information, otherwise, it

  // is NULL.  process is the one that will be dumped.  If

  // requesting_thread_id is meaningful and should be added to the

  // minidump, write_requester_stream is |true|.

  bool WriteMinidumpWithExceptionForProcess(DWORD requesting_thread_id,

                                            EXCEPTION_POINTERS* exinfo,

                                            MDRawAssertionInfo* assertion,

                                            HANDLE process,

                                            bool write_requester_stream);

  // Generates a new ID and stores it in next_minidump_id_, and stores the

  // path of the next minidump to be written in next_minidump_path_.

  void UpdateNextID();

  FilterCallback filter_;

  MinidumpCallback callback_;

  void* callback_context_;

  scoped_ptr<CrashGenerationClient> crash_generation_client_;

  // The directory in which a minidump will be written, set by the dump_path

  // argument to the constructor, or set_dump_path.

  wstring dump_path_;

  // The basename of the next minidump to be written, without the extension.

  wstring next_minidump_id_;

  // The full pathname of the next minidump to be written, including the file

  // extension.

  wstring next_minidump_path_;

  // Pointers to C-string representations of the above.  These are set when

  // the above wstring versions are set in order to avoid calling c_str during

  // an exception, as c_str may attempt to allocate heap memory.  These

  // pointers are not owned by the ExceptionHandler object, but their lifetimes

  // should be equivalent to the lifetimes of the associated wstring, provided

  // that the wstrings are not altered.

  const wchar_t* dump_path_c_;

  const wchar_t* next_minidump_id_c_;

  const wchar_t* next_minidump_path_c_;

  HMODULE dbghelp_module_;

  MiniDumpWriteDump_type minidump_write_dump_;

  MINIDUMP_TYPE dump_type_;

  HMODULE rpcrt4_module_;

  UuidCreate_type uuid_create_;

  // Tracks the handler types that were installed according to the

  // handler_types constructor argument.

  int handler_types_;

  // When installed_handler_ is true, previous_filter_ is the unhandled

  // exception filter that was set prior to installing ExceptionHandler as

  // the unhandled exception filter and pointing it to |this|.  NULL indicates

  // that there is no previous unhandled exception filter.

  LPTOP_LEVEL_EXCEPTION_FILTER previous_filter_;

#if _MSC_VER >= 1400  // MSVC 2005/8

  // Beginning in VC 8, the CRT provides an invalid parameter handler that will

  // be called when some CRT functions are passed invalid parameters.  In

  // earlier CRTs, the same conditions would cause unexpected behavior or

  // crashes.

  _invalid_parameter_handler previous_iph_;

#endif  // _MSC_VER >= 1400

  // The CRT allows you to override the default handler for pure

  // virtual function calls.

  _purecall_handler previous_pch_;

  // Vectored exception handler used for catching STATUS_HEAP_CORRUPTION

  // exceptions

  PVOID heap_corruption_veh_;

  // The exception handler thread.

  HANDLE handler_thread_;

  // True if the exception handler is being destroyed.

  // Starting with MSVC 2005, Visual C has stronger guarantees on volatile vars.

  // It has release semantics on write and acquire semantics on reads.

  // See the msdn documentation.

  volatile bool is_shutdown_;

  // The critical section enforcing the requirement that only one exception be

  // handled by a handler at a time.

  CRITICAL_SECTION handler_critical_section_;

  // Semaphores used to move exception handling between the exception thread

  // and the handler thread.  handler_start_semaphore_ is signalled by the

  // exception thread to wake up the handler thread when an exception occurs.

  // handler_finish_semaphore_ is signalled by the handler thread to wake up

  // the exception thread when handling is complete.

  HANDLE handler_start_semaphore_;

  HANDLE handler_finish_semaphore_;

  // The next 2 fields contain data passed from the requesting thread to

  // the handler thread.

  // The thread ID of the thread requesting the dump (either the exception

  // thread or any other thread that called WriteMinidump directly).

  DWORD requesting_thread_id_;

  // The exception info passed to the exception handler on the exception

  // thread, if an exception occurred.  NULL for user-requested dumps.

  EXCEPTION_POINTERS* exception_info_;

  // If the handler is invoked due to an assertion, this will contain a

  // pointer to the assertion information.  It is NULL at other times.

  MDRawAssertionInfo* assertion_;

  // The return value of the handler, passed from the handler thread back to

  // the requesting thread.

  MinidumpResult handler_return_value_;

  // If true, the handler will intercept EXCEPTION_BREAKPOINT and

  // EXCEPTION_SINGLE_STEP exceptions.  Leave this false (the default)

  // to not interfere with debuggers.

  bool handle_debug_exceptions_;

  // If true, the handler will consume any EXCEPTION_INVALID_HANDLE exceptions.

  // Leave this false (the default) to handle these exceptions as normal.

  bool consume_invalid_handle_exceptions_;

  // Callers can request additional memory regions to be included in

  // the dump.

  AppMemoryList app_memory_info_;

  // A stack of ExceptionHandler objects that have installed unhandled

  // exception filters.  This vector is used by HandleException to determine

  // which ExceptionHandler object to route an exception to.  When an

  // ExceptionHandler is created with install_handler true, it will append

  // itself to this list.

  static vector<ExceptionHandler*>* handler_stack_;

  // The index of the ExceptionHandler in handler_stack_ that will handle the

  // next exception.  Note that 0 means the last entry in handler_stack_, 1

  // means the next-to-last entry, and so on.  This is used by HandleException

  // to support multiple stacked Breakpad handlers.

  static LONG handler_stack_index_;

  // handler_stack_critical_section_ guards operations on handler_stack_ and

  // handler_stack_index_. The critical section is initialized by the

  // first instance of the class and destroyed by the last instance of it.

  static CRITICAL_SECTION handler_stack_critical_section_;

  // The number of instances of this class.

  static volatile LONG instance_count_;

  bool include_context_heap_;

  // disallow copy ctor and operator=

  explicit ExceptionHandler(const ExceptionHandler &);

  void operator=(const ExceptionHandler &);

};

}  // namespace google_breakpad

#pragma warning(pop)

#endif  // CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__