michael@0: // Copyright (c) 2006, 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: // exception_handler.h:  MacOS exception handler
michael@0: // This class can install a Mach exception port handler to trap most common
michael@0: // programming errors.  If an exception occurs, a minidump file will be
michael@0: // generated which contains detailed information about the process and the
michael@0: // exception.
michael@0: 
michael@0: #ifndef CLIENT_MAC_HANDLER_EXCEPTION_HANDLER_H__
michael@0: #define CLIENT_MAC_HANDLER_EXCEPTION_HANDLER_H__
michael@0: 
michael@0: #include <mach/mach.h>
michael@0: #include <TargetConditionals.h>
michael@0: 
michael@0: #include <string>
michael@0: 
michael@0: #include "common/scoped_ptr.h"
michael@0: 
michael@0: #if !TARGET_OS_IPHONE
michael@0: #include "client/mac/crash_generation/crash_generation_client.h"
michael@0: #endif
michael@0: 
michael@0: namespace google_breakpad {
michael@0: 
michael@0: using std::string;
michael@0: 
michael@0: struct ExceptionParameters;
michael@0: 
michael@0: enum HandlerThreadMessage {
michael@0:   // Message ID telling the handler thread to write a dump.
michael@0:   kWriteDumpMessage = 0,
michael@0:   // Message ID telling the handler thread to write a dump and include
michael@0:   // an exception stream.
michael@0:   kWriteDumpWithExceptionMessage = 1,
michael@0:   // Message ID telling the handler thread to quit.
michael@0:   kShutdownMessage = 2
michael@0: };
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, Breakpad
michael@0:   // will immediately report the exception as unhandled without writing a
michael@0:   // 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 <dump_dir>/<minidump_id>.dmp.
michael@0:   // |context| is the value passed into the constructor.
michael@0:   // |succeeded| indicates whether a minidump file was successfully written.
michael@0:   // Return true if the exception was fully handled and breakpad should exit.
michael@0:   // Return false to allow any other exception handlers to process the
michael@0:   // exception.
michael@0:   typedef bool (*MinidumpCallback)(const char *dump_dir,
michael@0:                                    const char *minidump_id,
michael@0:                                    void *context, bool succeeded);
michael@0: 
michael@0:   // A callback function which will be called directly if an exception occurs.
michael@0:   // This bypasses the minidump file writing and simply gives the client
michael@0:   // the exception information.
michael@0:   typedef bool (*DirectCallback)( void *context,
michael@0:                                   int exception_type,
michael@0:                                   int exception_code,
michael@0:                                   int exception_subcode,
michael@0:                                   mach_port_t thread_name);
michael@0: 
michael@0:   // Creates a new ExceptionHandler instance to handle writing minidumps.
michael@0:   // Minidump files will be written to dump_path, and the optional callback
michael@0:   // 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:   // If port_name is non-NULL, attempt to perform out-of-process dump generation
michael@0:   // If port_name is NULL, in-process dump generation will be used.
michael@0:   ExceptionHandler(const string &dump_path,
michael@0:                    FilterCallback filter, MinidumpCallback callback,
michael@0:                    void *callback_context, bool install_handler,
michael@0: 		   const char *port_name);
michael@0: 
michael@0:   // A special constructor if we want to bypass minidump writing and
michael@0:   // simply get a callback with the exception information.
michael@0:   ExceptionHandler(DirectCallback callback,
michael@0:                    void *callback_context,
michael@0:                    bool install_handler);
michael@0: 
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:     UpdateNextID();  // Necessary to put dump_path_ in next_minidump_path_.
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:     return WriteMinidump(false);
michael@0:   }
michael@0: 
michael@0:   bool WriteMinidump(bool write_exception_stream);
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, MinidumpCallback callback,
michael@0:                             void *callback_context) {
michael@0:     return WriteMinidump(dump_path, false, callback, callback_context);
michael@0:   }
michael@0: 
michael@0:   static bool WriteMinidump(const string &dump_path,
michael@0:                             bool write_exception_stream,
michael@0:                             MinidumpCallback callback,
michael@0:                             void *callback_context);
michael@0: 
michael@0:   // Write a minidump of child immediately. This can be used to capture
michael@0:   // the execution state of a child process independently of a crash.
michael@0:   static bool WriteMinidumpForChild(mach_port_t child,
michael@0: 				    mach_port_t child_blamed_thread,
michael@0: 				    const std::string &dump_path,
michael@0: 				    MinidumpCallback callback,
michael@0: 				    void *callback_context);
michael@0: 
michael@0:   // Returns whether out-of-process dump generation is used or not.
michael@0:   bool IsOutOfProcess() const {
michael@0: #if TARGET_OS_IPHONE
michael@0:     return false;
michael@0: #else
michael@0:     return crash_generation_client_.get() != NULL;
michael@0: #endif
michael@0:   }
michael@0: 
michael@0:  private:
michael@0:   // Install the mach exception handler
michael@0:   bool InstallHandler();
michael@0: 
michael@0:   // Uninstall the mach exception handler (if any)
michael@0:   bool UninstallHandler(bool in_exception);
michael@0: 
michael@0:   // Setup the handler thread, and if |install_handler| is true, install the
michael@0:   // mach exception port handler
michael@0:   bool Setup(bool install_handler);
michael@0: 
michael@0:   // Uninstall the mach exception handler (if any) and terminate the helper
michael@0:   // thread
michael@0:   bool Teardown();
michael@0: 
michael@0:   // Send a mach message to the exception handler.  Return true on
michael@0:   // success, false otherwise.
michael@0:   bool SendMessageToHandlerThread(HandlerThreadMessage message_id);
michael@0: 
michael@0:   // All minidump writing goes through this one routine.
michael@0:   // |task_context| can be NULL. If not, it will be used to retrieve the
michael@0:   // context of the current thread, instead of using |thread_get_state|.
michael@0:   bool WriteMinidumpWithException(int exception_type,
michael@0:                                   int exception_code,
michael@0:                                   int exception_subcode,
michael@0:                                   ucontext_t *task_context,
michael@0:                                   mach_port_t thread_name,
michael@0:                                   bool exit_after_write,
michael@0:                                   bool report_current_thread);
michael@0: 
michael@0:   // When installed, this static function will be call from a newly created
michael@0:   // pthread with |this| as the argument
michael@0:   static void *WaitForMessage(void *exception_handler_class);
michael@0: 
michael@0:   // Signal handler for SIGABRT.
michael@0:   static void SignalHandler(int sig, siginfo_t* info, void* uc);
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:   // Generates a new ID and stores it in next_minidump_id_, and stores the
michael@0:   // path of the next minidump to be written in next_minidump_path_.
michael@0:   void UpdateNextID();
michael@0: 
michael@0:   // These functions will suspend/resume all threads except for the
michael@0:   // reporting thread
michael@0:   bool SuspendThreads();
michael@0:   bool ResumeThreads();
michael@0: 
michael@0:   // The destination directory for the minidump
michael@0:   string dump_path_;
michael@0: 
michael@0:   // The basename of the next minidump w/o extension
michael@0:   string next_minidump_id_;
michael@0: 
michael@0:   // The full path to the next minidump to be written, including extension
michael@0:   string next_minidump_path_;
michael@0: 
michael@0:   // Pointers to the UTF-8 versions of above
michael@0:   const char *dump_path_c_;
michael@0:   const char *next_minidump_id_c_;
michael@0:   const char *next_minidump_path_c_;
michael@0: 
michael@0:   // The callback function and pointer to be passed back after the minidump
michael@0:   // has been written
michael@0:   FilterCallback filter_;
michael@0:   MinidumpCallback callback_;
michael@0:   void *callback_context_;
michael@0: 
michael@0:   // The callback function to be passed back when we don't want a minidump
michael@0:   // file to be written
michael@0:   DirectCallback directCallback_;
michael@0: 
michael@0:   // The thread that is created for the handler
michael@0:   pthread_t handler_thread_;
michael@0: 
michael@0:   // The port that is waiting on an exception message to be sent, if the
michael@0:   // handler is installed
michael@0:   mach_port_t handler_port_;
michael@0: 
michael@0:   // These variables save the previous exception handler's data so that it
michael@0:   // can be re-installed when this handler is uninstalled
michael@0:   ExceptionParameters *previous_;
michael@0: 
michael@0:   // True, if we've installed the exception handler
michael@0:   bool installed_exception_handler_;
michael@0: 
michael@0:   // True, if we're in the process of uninstalling the exception handler and
michael@0:   // the thread.
michael@0:   bool is_in_teardown_;
michael@0: 
michael@0:   // Save the last result of the last minidump
michael@0:   bool last_minidump_write_result_;
michael@0: 
michael@0:   // A mutex for use when writing out a minidump that was requested on a
michael@0:   // thread other than the exception handler.
michael@0:   pthread_mutex_t minidump_write_mutex_;
michael@0: 
michael@0:   // True, if we're using the mutext to indicate when mindump writing occurs
michael@0:   bool use_minidump_write_mutex_;
michael@0: 
michael@0:   // Old signal handler for SIGABRT. Used to be able to restore it when
michael@0:   // uninstalling.
michael@0:   scoped_ptr<struct sigaction> old_handler_;
michael@0: 
michael@0: #if !TARGET_OS_IPHONE
michael@0:   // Client for out-of-process dump generation.
michael@0:   scoped_ptr<CrashGenerationClient> crash_generation_client_;
michael@0: #endif
michael@0: };
michael@0: 
michael@0: }  // namespace google_breakpad
michael@0: 
michael@0: #endif  // CLIENT_MAC_HANDLER_EXCEPTION_HANDLER_H__