michael@0: // Copyright (c) 2007, Google Inc. michael@0: // All rights reserved. michael@0: // michael@0: // Redistribution and use in source and binary forms, with or without michael@0: // modification, are permitted provided that the following conditions are michael@0: // met: michael@0: // michael@0: // * Redistributions of source code must retain the above copyright michael@0: // notice, this list of conditions and the following disclaimer. michael@0: // * Redistributions in binary form must reproduce the above michael@0: // copyright notice, this list of conditions and the following disclaimer michael@0: // in the documentation and/or other materials provided with the michael@0: // distribution. michael@0: // * Neither the name of Google Inc. nor the names of its michael@0: // contributors may be used to endorse or promote products derived from michael@0: // this software without specific prior written permission. michael@0: // michael@0: // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS michael@0: // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT michael@0: // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR michael@0: // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT michael@0: // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT michael@0: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, michael@0: // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY michael@0: // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT michael@0: // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE michael@0: // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: // michael@0: // Author: Alfred Peng michael@0: michael@0: #ifndef CLIENT_SOLARIS_HANDLER_EXCEPTION_HANDLER_H__ michael@0: #define CLIENT_SOLARIS_HANDLER_EXCEPTION_HANDLER_H__ michael@0: michael@0: #include michael@0: #include michael@0: #include michael@0: michael@0: #include "client/solaris/handler/minidump_generator.h" michael@0: michael@0: namespace google_breakpad { michael@0: michael@0: using std::string; michael@0: michael@0: // michael@0: // ExceptionHandler michael@0: // michael@0: // ExceptionHandler can write a minidump file when an exception occurs, michael@0: // or when WriteMinidump() is called explicitly by your program. michael@0: // michael@0: // To have the exception handler write minidumps when an uncaught exception michael@0: // (crash) occurs, you should create an instance early in the execution michael@0: // of your program, and keep it around for the entire time you want to michael@0: // have crash handling active (typically, until shutdown). michael@0: // (NOTE): There should be only one this kind of exception handler michael@0: // object per process. michael@0: // michael@0: // If you want to write minidumps without installing the exception handler, michael@0: // you can create an ExceptionHandler with install_handler set to false, michael@0: // then call WriteMinidump. You can also use this technique if you want to michael@0: // use different minidump callbacks for different call sites. michael@0: // michael@0: // In either case, a callback function is called when a minidump is written, michael@0: // which receives the unqiue id of the minidump. The caller can use this michael@0: // id to collect and write additional application state, and to launch an michael@0: // external crash-reporting application. michael@0: // michael@0: // Caller should try to make the callbacks as crash-friendly as possible, michael@0: // it should avoid use heap memory allocation as much as possible. michael@0: // michael@0: class ExceptionHandler { michael@0: public: michael@0: // A callback function to run before Breakpad performs any substantial michael@0: // processing of an exception. A FilterCallback is called before writing michael@0: // a minidump. context is the parameter supplied by the user as michael@0: // callback_context when the handler was created. michael@0: // michael@0: // If a FilterCallback returns true, Breakpad will continue processing, michael@0: // attempting to write a minidump. If a FilterCallback returns false, michael@0: // Breakpad will immediately report the exception as unhandled without michael@0: // writing a minidump, allowing another handler the opportunity to handle it. michael@0: typedef bool (*FilterCallback)(void *context); michael@0: michael@0: // A callback function to run after the minidump has been written. michael@0: // minidump_id is a unique id for the dump, so the minidump michael@0: // file is /.dmp. context is the parameter supplied michael@0: // by the user as callback_context when the handler was created. succeeded michael@0: // indicates whether a minidump file was successfully written. michael@0: // michael@0: // If an exception occurred and the callback returns true, Breakpad will michael@0: // treat the exception as fully-handled, suppressing any other handlers from michael@0: // being notified of the exception. If the callback returns false, Breakpad michael@0: // will treat the exception as unhandled, and allow another handler to handle michael@0: // it. If there are no other handlers, Breakpad will report the exception to michael@0: // the system as unhandled, allowing a debugger or native crash dialog the michael@0: // opportunity to handle the exception. Most callback implementations michael@0: // should normally return the value of |succeeded|, or when they wish to michael@0: // not report an exception of handled, false. Callbacks will rarely want to michael@0: // return true directly (unless |succeeded| is true). michael@0: typedef bool (*MinidumpCallback)(const char *dump_path, michael@0: const char *minidump_id, michael@0: void *context, michael@0: bool succeeded); michael@0: michael@0: // Creates a new ExceptionHandler instance to handle writing minidumps. michael@0: // Before writing a minidump, the optional filter callback will be called. michael@0: // Its return value determines whether or not Breakpad should write a michael@0: // minidump. Minidump files will be written to dump_path, and the optional michael@0: // callback is called after writing the dump file, as described above. michael@0: // If install_handler is true, then a minidump will be written whenever michael@0: // an unhandled exception occurs. If it is false, minidumps will only michael@0: // be written when WriteMinidump is called. michael@0: ExceptionHandler(const string &dump_path, michael@0: FilterCallback filter, MinidumpCallback callback, michael@0: void *callback_context, michael@0: bool install_handler); michael@0: ~ExceptionHandler(); michael@0: michael@0: // Get and Set the minidump path. michael@0: string dump_path() const { return dump_path_; } michael@0: void set_dump_path(const string &dump_path) { michael@0: dump_path_ = dump_path; michael@0: dump_path_c_ = dump_path_.c_str(); michael@0: } michael@0: michael@0: // Writes a minidump immediately. This can be used to capture the michael@0: // execution state independently of a crash. Returns true on success. michael@0: bool WriteMinidump(); michael@0: michael@0: // Convenience form of WriteMinidump which does not require an michael@0: // ExceptionHandler instance. michael@0: static bool WriteMinidump(const string &dump_path, michael@0: MinidumpCallback callback, michael@0: void *callback_context); michael@0: michael@0: private: michael@0: // Setup crash handler. michael@0: void SetupHandler(); michael@0: // Setup signal handler for a signal. michael@0: void SetupHandler(int signo); michael@0: // Teardown the handler for a signal. michael@0: void TeardownHandler(int signo); michael@0: // Teardown all handlers. michael@0: void TeardownAllHandlers(); michael@0: michael@0: // Runs the main loop for the exception handler thread. michael@0: static void* ExceptionHandlerThreadMain(void *lpParameter); michael@0: michael@0: // Signal handler. michael@0: static void HandleException(int signo); michael@0: michael@0: // Write all the information to the dump file. michael@0: // If called from a signal handler, sighandler_ebp is the ebp of michael@0: // that signal handler's frame, and sig_ctx is an out parameter michael@0: // that will be set to point at the ucontext_t that was placed michael@0: // on the stack by the kernel. You can pass zero and NULL michael@0: // for the second and third parameters if you are not calling michael@0: // this from a signal handler. michael@0: bool InternalWriteMinidump(int signo, uintptr_t sighandler_ebp, michael@0: ucontext_t **sig_ctx); michael@0: michael@0: private: michael@0: // The callbacks before and after writing the dump file. michael@0: FilterCallback filter_; michael@0: MinidumpCallback callback_; michael@0: void *callback_context_; michael@0: michael@0: // The directory in which a minidump will be written, set by the dump_path michael@0: // argument to the constructor, or set_dump_path. michael@0: string dump_path_; michael@0: // C style dump path. Keep this when setting dump path, since calling michael@0: // c_str() of std::string when crashing may not be safe. michael@0: const char *dump_path_c_; michael@0: michael@0: // True if the ExceptionHandler installed an unhandled exception filter michael@0: // when created (with an install_handler parameter set to true). michael@0: bool installed_handler_; michael@0: michael@0: // Keep the previous handlers for the signal. michael@0: typedef void (*sighandler_t)(int); michael@0: std::map old_handlers_; michael@0: michael@0: // The global exception handler stack. This is need becuase there may exist michael@0: // multiple ExceptionHandler instances in a process. Each will have itself michael@0: // registered in this stack. michael@0: static std::vector *handler_stack_; michael@0: // The index of the handler that should handle the next exception. michael@0: static int handler_stack_index_; michael@0: static pthread_mutex_t handler_stack_mutex_; michael@0: michael@0: // The minidump generator. michael@0: MinidumpGenerator minidump_generator_; michael@0: michael@0: // disallow copy ctor and operator= michael@0: explicit ExceptionHandler(const ExceptionHandler &); michael@0: void operator=(const ExceptionHandler &); michael@0: }; michael@0: michael@0: } // namespace google_breakpad michael@0: michael@0: #endif // CLIENT_SOLARIS_HANDLER_EXCEPTION_HANDLER_H__