The Tor Browser / file revision

 // 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.

 // exception_handler.h:  MacOS exception handler

 // This class can install a Mach exception port handler to trap most common

 // programming errors.  If an exception occurs, a minidump file will be

 // generated which contains detailed information about the process and the

 // exception.

 #ifndef CLIENT_MAC_HANDLER_EXCEPTION_HANDLER_H__

 #define CLIENT_MAC_HANDLER_EXCEPTION_HANDLER_H__

 #include <mach/mach.h>

 #include <TargetConditionals.h>

 #include <string>

 #include "common/scoped_ptr.h"

 #if !TARGET_OS_IPHONE

 #include "client/mac/crash_generation/crash_generation_client.h"

 #endif

 namespace google_breakpad {

 using std::string;

 struct ExceptionParameters;

 enum HandlerThreadMessage {

   // Message ID telling the handler thread to write a dump.

   kWriteDumpMessage = 0,

   // Message ID telling the handler thread to write a dump and include

   // an exception stream.

   kWriteDumpWithExceptionMessage = 1,

   // Message ID telling the handler thread to quit.

   kShutdownMessage = 2

 };

 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.

   //

   // 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);

   // 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_dir>/<minidump_id>.dmp.

   // |context| is the value passed into the constructor.

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

   // Return true if the exception was fully handled and breakpad should exit.

   // Return false to allow any other exception handlers to process the

   // exception.

   typedef bool (*MinidumpCallback)(const char *dump_dir,

                                    const char *minidump_id,

                                    void *context, bool succeeded);

   // A callback function which will be called directly if an exception occurs.

   // This bypasses the minidump file writing and simply gives the client

   // the exception information.

   typedef bool (*DirectCallback)( void *context,

                                   int exception_type,

                                   int exception_code,

                                   int exception_subcode,

                                   mach_port_t thread_name);

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

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

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

   // If install_handler is true, then a minidump will be written whenever

   // an unhandled exception occurs.  If it is false, minidumps will only

   // be written when WriteMinidump is called.

   // If port_name is non-NULL, attempt to perform out-of-process dump generation

   // If port_name is NULL, in-process dump generation will be used.

   ExceptionHandler(const string &dump_path,

                    FilterCallback filter, MinidumpCallback callback,

                    void *callback_context, bool install_handler,

 		   const char *port_name);

   // A special constructor if we want to bypass minidump writing and

   // simply get a callback with the exception information.

   ExceptionHandler(DirectCallback callback,

                    void *callback_context,

                    bool install_handler);

   ~ExceptionHandler();

   // Get and set the minidump path.

   string dump_path() const { return dump_path_; }

   void set_dump_path(const string &dump_path) {

     dump_path_ = dump_path;

     dump_path_c_ = dump_path_.c_str();

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

   }

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

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

   bool WriteMinidump() {

     return WriteMinidump(false);

   }

   bool WriteMinidump(bool write_exception_stream);

   // Convenience form of WriteMinidump which does not require an

   // ExceptionHandler instance.

   static bool WriteMinidump(const string &dump_path, MinidumpCallback callback,

                             void *callback_context) {

     return WriteMinidump(dump_path, false, callback, callback_context);

   }

   static bool WriteMinidump(const string &dump_path,

                             bool write_exception_stream,

                             MinidumpCallback callback,

                             void *callback_context);

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

   // the execution state of a child process independently of a crash.

   static bool WriteMinidumpForChild(mach_port_t child,

 				    mach_port_t child_blamed_thread,

 				    const std::string &dump_path,

 				    MinidumpCallback callback,

 				    void *callback_context);

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

   bool IsOutOfProcess() const {

 #if TARGET_OS_IPHONE

     return false;

 #else

     return crash_generation_client_.get() != NULL;

 #endif

   }

  private:

   // Install the mach exception handler

   bool InstallHandler();

   // Uninstall the mach exception handler (if any)

   bool UninstallHandler(bool in_exception);

   // Setup the handler thread, and if |install_handler| is true, install the

   // mach exception port handler

   bool Setup(bool install_handler);

   // Uninstall the mach exception handler (if any) and terminate the helper

   // thread

   bool Teardown();

   // Send a mach message to the exception handler.  Return true on

   // success, false otherwise.

   bool SendMessageToHandlerThread(HandlerThreadMessage message_id);

   // All minidump writing goes through this one routine.

   // |task_context| can be NULL. If not, it will be used to retrieve the

   // context of the current thread, instead of using |thread_get_state|.

   bool WriteMinidumpWithException(int exception_type,

                                   int exception_code,

                                   int exception_subcode,

                                   ucontext_t *task_context,

                                   mach_port_t thread_name,

                                   bool exit_after_write,

                                   bool report_current_thread);

   // When installed, this static function will be call from a newly created

   // pthread with |this| as the argument

   static void *WaitForMessage(void *exception_handler_class);

   // Signal handler for SIGABRT.

   static void SignalHandler(int sig, siginfo_t* info, void* uc);

   // disallow copy ctor and operator=

   explicit ExceptionHandler(const ExceptionHandler &);

   void operator=(const ExceptionHandler &);

   // 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();

   // These functions will suspend/resume all threads except for the

   // reporting thread

   bool SuspendThreads();

   bool ResumeThreads();

   // The destination directory for the minidump

   string dump_path_;

   // The basename of the next minidump w/o extension

   string next_minidump_id_;

   // The full path to the next minidump to be written, including extension

   string next_minidump_path_;

   // Pointers to the UTF-8 versions of above

   const char *dump_path_c_;

   const char *next_minidump_id_c_;

   const char *next_minidump_path_c_;

   // The callback function and pointer to be passed back after the minidump

   // has been written

   FilterCallback filter_;

   MinidumpCallback callback_;

   void *callback_context_;

   // The callback function to be passed back when we don't want a minidump

   // file to be written

   DirectCallback directCallback_;

   // The thread that is created for the handler

   pthread_t handler_thread_;

   // The port that is waiting on an exception message to be sent, if the

   // handler is installed

   mach_port_t handler_port_;

   // These variables save the previous exception handler's data so that it

   // can be re-installed when this handler is uninstalled

   ExceptionParameters *previous_;

   // True, if we've installed the exception handler

   bool installed_exception_handler_;

   // True, if we're in the process of uninstalling the exception handler and

   // the thread.

   bool is_in_teardown_;

   // Save the last result of the last minidump

   bool last_minidump_write_result_;

   // A mutex for use when writing out a minidump that was requested on a

   // thread other than the exception handler.

   pthread_mutex_t minidump_write_mutex_;

   // True, if we're using the mutext to indicate when mindump writing occurs

   bool use_minidump_write_mutex_;

   // Old signal handler for SIGABRT. Used to be able to restore it when

   // uninstalling.

   scoped_ptr<struct sigaction> old_handler_;

 #if !TARGET_OS_IPHONE

   // Client for out-of-process dump generation.

   scoped_ptr<CrashGenerationClient> crash_generation_client_;

 #endif

 };

 }  // namespace google_breakpad

 #endif  // CLIENT_MAC_HANDLER_EXCEPTION_HANDLER_H__