| // 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 "client/windows/common/ipc_protocol.h" |
| #include "client/windows/crash_generation/crash_generation_client.h" |
| #include "common/scoped_ptr.h" |
| #include "google_breakpad/common/minidump_format.h" |
| |
| namespace google_breakpad { |
| |
| using std::vector; |
| using std::wstring; |
| |
| // These entries store a list of memory regions that the client wants included |
| // in the minidump. |
| struct AppMemory { |
| ULONG64 ptr; |
| ULONG length; |
| |
| bool operator==(const struct AppMemory& other) const { |
| return ptr == other.ptr; |
| } |
| |
| bool operator==(const void* other) const { |
| return ptr == reinterpret_cast<ULONG64>(other); |
| } |
| }; |
| typedef std::list<AppMemory> AppMemoryList; |
| |
| class ExceptionHandler { |
| public: |
| // 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 true, Breakpad will continue processing, |
| // attempting to write a minidump. If a FilterCallback returns false, |
| // Breakpad will immediately report the exception as unhandled without |
| // writing a minidump, allowing another handler the opportunity to handle it. |
| typedef bool (*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, |
| 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_ALL = HANDLER_EXCEPTION | |
| HANDLER_INVALID_PARAMETER | |
| HANDLER_PURECALL |
| }; |
| |
| // 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); |
| |
| 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 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); |
| |
| // 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. |
| bool WriteMinidumpWithException(DWORD requesting_thread_id, |
| EXCEPTION_POINTERS* exinfo, |
| MDRawAssertionInfo* assertion); |
| |
| // This function is used as a callback when calling MinidumpWriteDump, |
| // in order to add additional memory regions to the dump. |
| static BOOL CALLBACK MinidumpWriteDumpCallback( |
| PVOID context, |
| const PMINIDUMP_CALLBACK_INPUT callback_input, |
| PMINIDUMP_CALLBACK_OUTPUT callback_output); |
| |
| // 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_; |
| |
| // 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. |
| bool 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_; |
| |
| // 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__ |