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/. */
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.
12 #ifndef nsExceptionHandler_h__
13 #define nsExceptionHandler_h__
15 #include "mozilla/Assertions.h"
16 #include "mozilla/EnumeratedArray.h"
18 #include "CrashAnnotations.h"
24 #include "nsXULAppAPI.h"
28 # ifdef WIN32_LEAN_AND_MEAN
29 # undef WIN32_LEAN_AND_MEAN
34 #if defined(XP_MACOSX)
35 # include <mach/mach.h>
44 namespace CrashReporter
{
47 * Returns true if the crash reporter is using the dummy implementation.
49 static inline bool IsDummy() {
50 #ifdef MOZ_CRASHREPORTER
57 nsresult
SetExceptionHandler(nsIFile
* aXREDirectory
, bool force
= false);
58 nsresult
UnsetExceptionHandler();
61 * Tell the crash reporter to recalculate where crash events files should go.
62 * SetCrashEventsDir is used before XPCOM is initialized from the startup
65 * UpdateCrashEventsDir uses the directory service to re-set the
66 * crash event directory based on the current profile.
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
73 void SetUserAppDataDirectory(nsIFile
* aDir
);
74 void SetProfileDirectory(nsIFile
* aDir
);
75 void UpdateCrashEventsDir();
76 void SetMemoryReportFile(nsIFile
* aFile
);
77 nsresult
GetDefaultMemoryReportFile(nsIFile
** aFile
);
78 void SetTelemetrySessionId(const nsACString
& id
);
81 * Get the path where crash event files should be written.
83 bool GetCrashEventsDir(nsAString
& aPath
);
86 bool GetServerURL(nsACString
& aServerURL
);
87 nsresult
SetServerURL(const nsACString
& aServerURL
);
88 bool GetMinidumpPath(nsAString
& aPath
);
89 nsresult
SetMinidumpPath(const nsAString
& aPath
);
91 // AnnotateCrashReport, RemoveCrashReportAnnotation and
92 // AppendAppNotesToCrashReport may be called from any thread in a chrome
93 // process, but may only be called from the main thread in a content process.
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
);
101 // Called after the crash reporter client has been created in a content
102 // process, allowing annotations to be processed.
103 void NotifyCrashReporterClientCreated();
105 void AnnotateOOMAllocationSize(size_t size
);
106 void AnnotateTexturesSize(size_t size
);
107 nsresult
SetGarbageCollecting(bool collecting
);
108 void SetEventloopNestingLevel(uint32_t level
);
109 void SetMinidumpAnalysisAllThreads();
111 nsresult
SetRestartArgs(int argc
, char** argv
);
112 nsresult
SetupExtraData(nsIFile
* aAppDataDirectory
, const nsACString
& aBuildID
);
113 // Registers an additional memory region to be included in the minidump
114 nsresult
RegisterAppMemory(void* ptr
, size_t length
);
115 nsresult
UnregisterAppMemory(void* ptr
);
117 // Include heap regions of the crash context.
118 void SetIncludeContextHeap(bool aValue
);
120 // Functions for working with minidumps and .extras
121 typedef mozilla::EnumeratedArray
<Annotation
, Annotation::Count
, nsCString
>
123 void DeleteMinidumpFilesForID(const nsAString
& id
);
124 bool GetMinidumpForID(const nsAString
& id
, nsIFile
** minidump
);
125 bool GetIDFromMinidump(nsIFile
* minidump
, nsAString
& id
);
126 bool GetExtraFileForID(const nsAString
& id
, nsIFile
** extraFile
);
127 bool GetExtraFileForMinidump(nsIFile
* minidump
, nsIFile
** extraFile
);
128 bool WriteExtraFile(const nsAString
& id
, const AnnotationTable
& annotations
);
131 * Copies the non-empty annotations in the source table to the destination
132 * overwriting the corresponding entries.
134 void MergeCrashAnnotations(AnnotationTable
& aDst
, const AnnotationTable
& aSrc
);
137 nsresult
WriteMinidumpForException(EXCEPTION_POINTERS
* aExceptionInfo
);
140 bool WriteMinidumpForSigInfo(int signo
, siginfo_t
* info
, void* uc
);
143 nsresult
AppendObjCExceptionInfoToAppNotes(void* inException
);
145 nsresult
GetSubmitReports(bool* aSubmitReport
);
146 nsresult
SetSubmitReports(bool aSubmitReport
);
148 // Out-of-process crash reporter API.
150 // Initializes out-of-process crash reporting. This method must be called
151 // before the platform-specific notification pipe APIs are called. If called
152 // from off the main thread, this method will synchronously proxy to the main
157 * Takes a minidump for the current process and returns the dump file.
158 * Callers are responsible for managing the resulting file.
160 * @param aResult - file pointer that holds the resulting minidump.
161 * @param aMoveToPending - if true move the report to the report
163 * @returns boolean indicating success or failure.
165 bool TakeMinidump(nsIFile
** aResult
, bool aMoveToPending
= false);
167 // Return true if a dump was found for |childPid|, and return the
168 // path in |dump|. The caller owns the last reference to |dump| if it
169 // is non-nullptr. The annotations for the crash will be stored in
170 // |aAnnotations|. The sequence parameter will be filled with an ordinal
171 // indicating which remote process crashed first.
172 bool TakeMinidumpForChild(uint32_t childPid
, nsIFile
** dump
,
173 AnnotationTable
& aAnnotations
,
174 uint32_t* aSequence
= nullptr);
177 * If a dump was found for |childPid| then write a minimal .extra file to
178 * complete it and remove it from the list of pending crash dumps. It's
179 * required to call this method after a non-main process crash if the crash
180 * report could not be finalized via the CrashReporterHost (for example because
181 * it wasn't instanced yet).
183 * @param aChildPid The pid of the crashed child process
184 * @param aType The type of the crashed process
186 bool FinalizeOrphanedMinidump(uint32_t aChildPid
, GeckoProcessType aType
);
189 typedef HANDLE ProcessHandle
;
190 typedef DWORD ProcessId
;
191 typedef DWORD ThreadId
;
192 typedef HANDLE FileHandle
;
193 #elif defined(XP_MACOSX)
194 typedef task_t ProcessHandle
;
195 typedef pid_t ProcessId
;
196 typedef mach_port_t ThreadId
;
197 typedef int FileHandle
;
199 typedef int ProcessHandle
;
200 typedef pid_t ProcessId
;
201 typedef int ThreadId
;
202 typedef int FileHandle
;
206 int GetAnnotationTimeCrashFd();
208 void RegisterChildCrashAnnotationFileDescriptor(ProcessId aProcess
,
210 void DeregisterChildCrashAnnotationFileDescriptor(ProcessId aProcess
);
212 // Return the current thread's ID.
214 // XXX: this is a somewhat out-of-place interface to expose through
215 // crashreporter, but it takes significant work to call sys_gettid()
216 // correctly on Linux and breakpad has already jumped through those
218 ThreadId
CurrentThreadId();
221 * Take a minidump of the target process and pair it with an incoming minidump
222 * provided by the caller or a new minidump of the calling process and thread.
223 * The caller will own both dumps after this call. If this function fails
224 * it will attempt to delete any files that were created.
226 * The .extra information created will not include an 'additional_minidumps'
229 * @param aTargetPid The target process for the minidump.
230 * @param aTargetBlamedThread The target thread for the minidump.
231 * @param aIncomingPairName The name to apply to the paired dump the caller
233 * @param aIncomingDumpToPair Existing dump to pair with the new dump. if this
234 * is null, TakeMinidumpAndPair will take a new minidump of the calling
235 * process and thread and use it in aIncomingDumpToPairs place.
236 * @param aTargetDumpOut The target minidump file paired up with
237 * aIncomingDumpToPair.
238 * @param aTargetAnnotations The crash annotations of the target process.
239 * @return bool indicating success or failure
241 bool CreateMinidumpsAndPair(ProcessHandle aTargetPid
,
242 ThreadId aTargetBlamedThread
,
243 const nsACString
& aIncomingPairName
,
244 nsIFile
* aIncomingDumpToPair
,
245 AnnotationTable
& aTargetAnnotations
,
246 nsIFile
** aTargetDumpOut
);
248 // Create an additional minidump for a child of a process which already has
249 // a minidump (|parentMinidump|).
250 // The resulting dump will get the id of the parent and use the |name| as
252 bool CreateAdditionalChildMinidump(ProcessHandle childPid
,
253 ThreadId childBlamedThread
,
254 nsIFile
* parentMinidump
,
255 const nsACString
& name
);
257 #if defined(XP_WIN) || defined(XP_MACOSX)
258 // Parent-side API for children
259 const char* GetChildNotificationPipe();
261 # ifdef MOZ_CRASHREPORTER_INJECTOR
262 // Inject a crash report client into an arbitrary process, and inform the
263 // callback object when it crashes. Parent process only.
265 class InjectorCrashCallback
{
267 InjectorCrashCallback() {}
270 * Inform the callback of a crash. The client code should call
271 * TakeMinidumpForChild to remove it from the PID mapping table.
273 * The callback will not be fired if the client has already called
274 * TakeMinidumpForChild for this process ID.
276 virtual void OnCrash(DWORD processID
) = 0;
279 // This method implies OOPInit
280 void InjectCrashReporterIntoProcess(DWORD processID
, InjectorCrashCallback
* cb
);
281 void UnregisterInjectorCallback(DWORD processID
);
286 bool SetRemoteExceptionHandler(const nsACString
& crashPipe
,
287 uintptr_t aCrashTimeAnnotationFile
);
289 bool SetRemoteExceptionHandler(const nsACString
& crashPipe
);
293 // Parent-side API for children
295 // Set the outparams for crash reporter server's fd (|childCrashFd|)
296 // and the magic fd number it should be remapped to
297 // (|childCrashRemapFd|) before exec() in the child process.
298 // |SetRemoteExceptionHandler()| in the child process expects to find
299 // the server at |childCrashRemapFd|. Return true iff successful.
301 // If crash reporting is disabled, both outparams will be set to -1
302 // and |true| will be returned.
303 bool CreateNotificationPipeForChild(int* childCrashFd
, int* childCrashRemapFd
);
306 bool SetRemoteExceptionHandler();
310 bool UnsetRemoteExceptionHandler();
312 #if defined(MOZ_WIDGET_ANDROID)
313 // Android creates child process as services so we must explicitly set
314 // the handle for the pipe since it can't get remapped to a default value.
315 void SetNotificationPipeForChild(int childCrashFd
);
316 void SetCrashAnnotationPipeForChild(int childCrashAnnotationFd
);
318 // Android builds use a custom library loader, so /proc/<pid>/maps
319 // will just show anonymous mappings for all the non-system
320 // shared libraries. This API is to work around that by providing
321 // info about the shared libraries that are mapped into these anonymous
323 void AddLibraryMapping(const char* library_name
, uintptr_t start_address
,
324 size_t mapping_length
, size_t file_offset
);
328 // Annotates the crash report with the name of the calling thread.
329 void SetCurrentThreadName(const char* aName
);
331 } // namespace CrashReporter
333 #endif /* nsExceptionHandler_h__ */