toolkit/crashreporter/nsExceptionHandler.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 // This header has two implementations, the real one in nsExceptionHandler.cpp
   7 // and a dummy in nsDummyExceptionHandler.cpp. The latter is used in builds
   8 // configured with --disable-crashreporter. If you add or remove a function
   9 // from this header you must update both implementations otherwise you'll break
  10 // builds that disable the crash reporter.
  11
  12 #ifndef nsExceptionHandler_h__
  13 #define nsExceptionHandler_h__
  14
  15 #include "mozilla/Assertions.h"
  16 #include "mozilla/EnumeratedArray.h"
  17
  18 #include "CrashAnnotations.h"
  19
  20 #include <stddef.h>
  21 #include <stdint.h>
  22 #include "nsError.h"
  23 #include "nsString.h"
  24 #include "nsXULAppAPI.h"
  25 #include "prio.h"
  26
  27 #if defined(XP_WIN)
  28 #  ifdef WIN32_LEAN_AND_MEAN
  29 #    undef WIN32_LEAN_AND_MEAN
  30 #  endif
  31 #  include <windows.h>
  32 #endif
  33
  34 #if defined(XP_MACOSX)
  35 #  include <mach/mach.h>
  36 #endif
  37
  38 #if defined(XP_LINUX)
  39 #  include <signal.h>
  40 #endif
  41
  42 class nsIFile;
  43
  44 namespace CrashReporter {
  45
  46 /**
  47  * Returns true if the crash reporter is using the dummy implementation.
  48  */
  49 static inline bool IsDummy() {
  50 #ifdef MOZ_CRASHREPORTER
  51   return false;
  52 #else
  53   return true;
  54 #endif
  55 }
  56
  57 nsresult SetExceptionHandler(nsIFile* aXREDirectory, bool force = false);
  58 nsresult UnsetExceptionHandler();
  59
  60 /**
  61  * Tell the crash reporter to recalculate where crash events files should go.
  62  * SetCrashEventsDir is used before XPCOM is initialized from the startup
  63  * code.
  64  *
  65  * UpdateCrashEventsDir uses the directory service to re-set the
  66  * crash event directory based on the current profile.
  67  *
  68  * 1. If environment variable is present, use it. We don't expect
  69  *    the environment variable except for tests and other atypical setups.
  70  * 2. <profile>/crashes/events
  71  * 3. <UAppData>/Crash Reports/events
  72  */
  73 void SetUserAppDataDirectory(nsIFile* aDir);
  74 void SetProfileDirectory(nsIFile* aDir);
  75 void UpdateCrashEventsDir();
  76 void SetMemoryReportFile(nsIFile* aFile);
  77 nsresult GetDefaultMemoryReportFile(nsIFile** aFile);
  78
  79 /**
  80  * Get the path where crash event files should be written.
  81  */
  82 bool GetCrashEventsDir(nsAString& aPath);
  83
  84 bool GetEnabled();
  85 bool GetServerURL(nsACString& aServerURL);
  86 nsresult SetServerURL(const nsACString& aServerURL);
  87 bool GetMinidumpPath(nsAString& aPath);
  88 nsresult SetMinidumpPath(const nsAString& aPath);
  89
  90 // These functions are thread safe and can be called in both the parent and
  91 // child processes. Annotations added in the main process will be included in
  92 // child process crashes too unless the child process sets its own annotations.
  93 // If it does the child-provided annotation overrides the one set in the parent.
  94 nsresult AnnotateCrashReport(Annotation key, bool data);
  95 nsresult AnnotateCrashReport(Annotation key, int data);
  96 nsresult AnnotateCrashReport(Annotation key, unsigned int data);
  97 nsresult AnnotateCrashReport(Annotation key, const nsACString& data);
  98 nsresult RemoveCrashReportAnnotation(Annotation key);
  99 nsresult AppendAppNotesToCrashReport(const nsACString& data);
 100
 101 // RAII class for setting a crash annotation during a limited scope of time.
 102 // Will reset the named annotation to its previous value when destroyed.
 103 //
 104 // This type's behavior is identical to that of AnnotateCrashReport().
 105 class MOZ_RAII AutoAnnotateCrashReport final {
 106  public:
 107   AutoAnnotateCrashReport(Annotation key, bool data);
 108   AutoAnnotateCrashReport(Annotation key, int data);
 109   AutoAnnotateCrashReport(Annotation key, unsigned int data);
 110   AutoAnnotateCrashReport(Annotation key, const nsACString& data);
 111   ~AutoAnnotateCrashReport();
 112
 113 #ifdef MOZ_CRASHREPORTER
 114  private:
 115   Annotation mKey;
 116   nsCString mPrevious;
 117 #endif
 118 };
 119
 120 void AnnotateOOMAllocationSize(size_t size);
 121 void AnnotateTexturesSize(size_t size);
 122 nsresult SetGarbageCollecting(bool collecting);
 123 void SetEventloopNestingLevel(uint32_t level);
 124 void SetMinidumpAnalysisAllThreads();
 125
 126 nsresult SetRestartArgs(int argc, char** argv);
 127 nsresult SetupExtraData(nsIFile* aAppDataDirectory, const nsACString& aBuildID);
 128 // Registers an additional memory region to be included in the minidump
 129 nsresult RegisterAppMemory(void* ptr, size_t length);
 130 nsresult UnregisterAppMemory(void* ptr);
 131
 132 // Include heap regions of the crash context.
 133 void SetIncludeContextHeap(bool aValue);
 134
 135 void GetAnnotation(uint32_t childPid, Annotation annotation,
 136                    nsACString& outStr);
 137
 138 // Functions for working with minidumps and .extras
 139 typedef mozilla::EnumeratedArray<Annotation, Annotation::Count, nsCString>
 140     AnnotationTable;
 141 void DeleteMinidumpFilesForID(const nsAString& id);
 142 bool GetMinidumpForID(const nsAString& id, nsIFile** minidump);
 143 bool GetIDFromMinidump(nsIFile* minidump, nsAString& id);
 144 bool GetExtraFileForID(const nsAString& id, nsIFile** extraFile);
 145 bool GetExtraFileForMinidump(nsIFile* minidump, nsIFile** extraFile);
 146 bool WriteExtraFile(const nsAString& id, const AnnotationTable& annotations);
 147
 148 /**
 149  * Copies the non-empty annotations in the source table to the destination
 150  * overwriting the corresponding entries.
 151  */
 152 void MergeCrashAnnotations(AnnotationTable& aDst, const AnnotationTable& aSrc);
 153
 154 #ifdef XP_WIN
 155 nsresult WriteMinidumpForException(EXCEPTION_POINTERS* aExceptionInfo);
 156 #endif
 157 #ifdef XP_LINUX
 158 bool WriteMinidumpForSigInfo(int signo, siginfo_t* info, void* uc);
 159 #endif
 160 #ifdef XP_MACOSX
 161 nsresult AppendObjCExceptionInfoToAppNotes(void* inException);
 162 #endif
 163 nsresult GetSubmitReports(bool* aSubmitReport);
 164 nsresult SetSubmitReports(bool aSubmitReport);
 165
 166 // Out-of-process crash reporter API.
 167
 168 #ifdef XP_WIN
 169 // This data is stored in the parent process, there is one copy for each child
 170 // process. The mChildPid and mMinidumpFile fields are filled by the WER runtime
 171 // exception module when the associated child process crashes.
 172 struct WindowsErrorReportingData {
 173   // Points to the WerNotifyProc function.
 174   LPTHREAD_START_ROUTINE mWerNotifyProc;
 175   // PID of the child process that crashed.
 176   DWORD mChildPid;
 177   // Filename of the generated minidump; this is not a 0-terminated string
 178   char mMinidumpFile[40];
 179   // OOM allocation size for the crash (ignore if zero)
 180   size_t mOOMAllocationSize;
 181 };
 182 #endif  // XP_WIN
 183
 184 // Initializes out-of-process crash reporting. This method must be called
 185 // before the platform-specific notification pipe APIs are called. If called
 186 // from off the main thread, this method will synchronously proxy to the main
 187 // thread.
 188 void OOPInit();
 189
 190 // Return true if a dump was found for |childPid|, and return the
 191 // path in |dump|.  The caller owns the last reference to |dump| if it
 192 // is non-nullptr. The annotations for the crash will be stored in
 193 // |aAnnotations|. The sequence parameter will be filled with an ordinal
 194 // indicating which remote process crashed first.
 195 bool TakeMinidumpForChild(uint32_t childPid, nsIFile** dump,
 196                           AnnotationTable& aAnnotations,
 197                           uint32_t* aSequence = nullptr);
 198
 199 /**
 200  * If a dump was found for |childPid| then write a minimal .extra file to
 201  * complete it and remove it from the list of pending crash dumps. It's
 202  * required to call this method after a non-main process crash if the crash
 203  * report could not be finalized via the CrashReporterHost (for example because
 204  * it wasn't instanced yet).
 205  *
 206  * @param aChildPid The pid of the crashed child process
 207  * @param aType The type of the crashed process
 208  * @param aDumpId A string that will be filled with the dump ID
 209  */
 210 [[nodiscard]] bool FinalizeOrphanedMinidump(uint32_t aChildPid,
 211                                             GeckoProcessType aType,
 212                                             nsString* aDumpId = nullptr);
 213
 214 #if defined(XP_WIN)
 215 typedef HANDLE ProcessHandle;
 216 typedef DWORD ProcessId;
 217 typedef DWORD ThreadId;
 218 typedef HANDLE FileHandle;
 219 const FileHandle kInvalidFileHandle = INVALID_HANDLE_VALUE;
 220 #elif defined(XP_MACOSX)
 221 typedef task_t ProcessHandle;
 222 typedef pid_t ProcessId;
 223 typedef mach_port_t ThreadId;
 224 typedef int FileHandle;
 225 const FileHandle kInvalidFileHandle = -1;
 226 #else
 227 typedef int ProcessHandle;
 228 typedef pid_t ProcessId;
 229 typedef int ThreadId;
 230 typedef int FileHandle;
 231 const FileHandle kInvalidFileHandle = -1;
 232 #endif
 233
 234 #if !defined(XP_WIN)
 235 FileHandle GetAnnotationTimeCrashFd();
 236 #endif
 237 void RegisterChildCrashAnnotationFileDescriptor(ProcessId aProcess,
 238                                                 PRFileDesc* aFd);
 239 void DeregisterChildCrashAnnotationFileDescriptor(ProcessId aProcess);
 240
 241 // Return the current thread's ID.
 242 //
 243 // XXX: this is a somewhat out-of-place interface to expose through
 244 // crashreporter, but it takes significant work to call sys_gettid()
 245 // correctly on Linux and breakpad has already jumped through those
 246 // hoops for us.
 247 ThreadId CurrentThreadId();
 248
 249 /*
 250  * Take a minidump of the target process and pair it with an incoming minidump
 251  * provided by the caller or a new minidump of the calling process and thread.
 252  * The caller will own both dumps after this call. If this function fails
 253  * it will attempt to delete any files that were created.
 254  *
 255  * The .extra information created will not include an 'additional_minidumps'
 256  * annotation.
 257  *
 258  * @param aTargetPid The target process for the minidump.
 259  * @param aTargetBlamedThread The target thread for the minidump.
 260  * @param aIncomingPairName The name to apply to the paired dump the caller
 261  *   passes in.
 262  * @param aIncomingDumpToPair Existing dump to pair with the new dump. if this
 263  *   is null, TakeMinidumpAndPair will take a new minidump of the calling
 264  *   process and thread and use it in aIncomingDumpToPairs place.
 265  * @param aTargetDumpOut The target minidump file paired up with
 266  *   aIncomingDumpToPair.
 267  * @param aTargetAnnotations The crash annotations of the target process.
 268  * @return bool indicating success or failure
 269  */
 270 bool CreateMinidumpsAndPair(ProcessHandle aTargetPid,
 271                             ThreadId aTargetBlamedThread,
 272                             const nsACString& aIncomingPairName,
 273                             nsIFile* aIncomingDumpToPair,
 274                             AnnotationTable& aTargetAnnotations,
 275                             nsIFile** aTargetDumpOut);
 276
 277 // Create an additional minidump for a child of a process which already has
 278 // a minidump (|parentMinidump|).
 279 // The resulting dump will get the id of the parent and use the |name| as
 280 // an extension.
 281 bool CreateAdditionalChildMinidump(ProcessHandle childPid,
 282                                    ThreadId childBlamedThread,
 283                                    nsIFile* parentMinidump,
 284                                    const nsACString& name);
 285
 286 #if defined(XP_WIN) || defined(XP_MACOSX)
 287 // Parent-side API for children
 288 const char* GetChildNotificationPipe();
 289
 290 #  ifdef MOZ_CRASHREPORTER_INJECTOR
 291 // Inject a crash report client into an arbitrary process, and inform the
 292 // callback object when it crashes. Parent process only.
 293
 294 class InjectorCrashCallback {
 295  public:
 296   InjectorCrashCallback() {}
 297
 298   /**
 299    * Inform the callback of a crash. The client code should call
 300    * TakeMinidumpForChild to remove it from the PID mapping table.
 301    *
 302    * The callback will not be fired if the client has already called
 303    * TakeMinidumpForChild for this process ID.
 304    */
 305   virtual void OnCrash(DWORD processID) = 0;
 306 };
 307
 308 // This method implies OOPInit
 309 void InjectCrashReporterIntoProcess(DWORD processID, InjectorCrashCallback* cb);
 310 void UnregisterInjectorCallback(DWORD processID);
 311 #  endif
 312 #else
 313 // Parent-side API for children
 314
 315 // Set the outparams for crash reporter server's fd (|childCrashFd|)
 316 // and the magic fd number it should be remapped to
 317 // (|childCrashRemapFd|) before exec() in the child process.
 318 // |SetRemoteExceptionHandler()| in the child process expects to find
 319 // the server at |childCrashRemapFd|.  Return true if successful.
 320 //
 321 // If crash reporting is disabled, both outparams will be set to -1
 322 // and |true| will be returned.
 323 bool CreateNotificationPipeForChild(int* childCrashFd, int* childCrashRemapFd);
 324
 325 #endif  // XP_WIN
 326
 327 // Windows Error Reporting helper
 328 #if defined(XP_WIN)
 329 DWORD WINAPI WerNotifyProc(LPVOID aParameter);
 330 #endif
 331
 332 // Child-side API
 333 bool SetRemoteExceptionHandler(
 334     const char* aCrashPipe = nullptr,
 335     FileHandle aCrashTimeAnnotationFile = kInvalidFileHandle);
 336 bool UnsetRemoteExceptionHandler();
 337
 338 #if defined(MOZ_WIDGET_ANDROID)
 339 // Android creates child process as services so we must explicitly set
 340 // the handle for the pipe since it can't get remapped to a default value.
 341 void SetNotificationPipeForChild(FileHandle childCrashFd);
 342 void SetCrashAnnotationPipeForChild(FileHandle childCrashAnnotationFd);
 343 #endif
 344
 345 // Annotates the crash report with the name of the calling thread.
 346 void SetCurrentThreadName(const char* aName);
 347
 348 }  // namespace CrashReporter
 349
 350 #endif /* nsExceptionHandler_h__ */