1 | // Copyright (c) 2010 Google Inc. |
2 | // All rights reserved. |
3 | // |
4 | // Redistribution and use in source and binary forms, with or without |
5 | // modification, are permitted provided that the following conditions are |
6 | // met: |
7 | // |
8 | // * Redistributions of source code must retain the above copyright |
9 | // notice, this list of conditions and the following disclaimer. |
10 | // * Redistributions in binary form must reproduce the above |
11 | // copyright notice, this list of conditions and the following disclaimer |
12 | // in the documentation and/or other materials provided with the |
13 | // distribution. |
14 | // * Neither the name of Google Inc. nor the names of its |
15 | // contributors may be used to endorse or promote products derived from |
16 | // this software without specific prior written permission. |
17 | // |
18 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
19 | // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
20 | // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
21 | // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
22 | // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
23 | // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
24 | // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
25 | // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
26 | // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
27 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
28 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
29 | |
30 | #ifndef CLIENT_LINUX_HANDLER_EXCEPTION_HANDLER_H_ |
31 | #define CLIENT_LINUX_HANDLER_EXCEPTION_HANDLER_H_ |
32 | |
33 | #include <signal.h> |
34 | #include <stdint.h> |
35 | #include <stdio.h> |
36 | #include <sys/ucontext.h> |
37 | |
38 | #include <string> |
39 | |
40 | #include "client/linux/crash_generation/crash_generation_client.h" |
41 | #include "client/linux/handler/minidump_descriptor.h" |
42 | #include "client/linux/minidump_writer/minidump_writer.h" |
43 | #include "common/scoped_ptr.h" |
44 | #include "common/using_std_string.h" |
45 | #include "google_breakpad/common/minidump_format.h" |
46 | |
47 | namespace google_breakpad { |
48 | |
49 | // ExceptionHandler |
50 | // |
51 | // ExceptionHandler can write a minidump file when an exception occurs, |
52 | // or when WriteMinidump() is called explicitly by your program. |
53 | // |
54 | // To have the exception handler write minidumps when an uncaught exception |
55 | // (crash) occurs, you should create an instance early in the execution |
56 | // of your program, and keep it around for the entire time you want to |
57 | // have crash handling active (typically, until shutdown). |
58 | // (NOTE): There should be only be one this kind of exception handler |
59 | // object per process. |
60 | // |
61 | // If you want to write minidumps without installing the exception handler, |
62 | // you can create an ExceptionHandler with install_handler set to false, |
63 | // then call WriteMinidump. You can also use this technique if you want to |
64 | // use different minidump callbacks for different call sites. |
65 | // |
66 | // In either case, a callback function is called when a minidump is written, |
67 | // which receives the full path or file descriptor of the minidump. The |
68 | // caller can collect and write additional application state to that minidump, |
69 | // and launch an external crash-reporting application. |
70 | // |
71 | // Caller should try to make the callbacks as crash-friendly as possible, |
72 | // it should avoid use heap memory allocation as much as possible. |
73 | |
74 | class ExceptionHandler { |
75 | public: |
76 | // A callback function to run before Breakpad performs any substantial |
77 | // processing of an exception. A FilterCallback is called before writing |
78 | // a minidump. |context| is the parameter supplied by the user as |
79 | // callback_context when the handler was created. |
80 | // |
81 | // If a FilterCallback returns true, Breakpad will continue processing, |
82 | // attempting to write a minidump. If a FilterCallback returns false, |
83 | // Breakpad will immediately report the exception as unhandled without |
84 | // writing a minidump, allowing another handler the opportunity to handle it. |
85 | typedef bool (*FilterCallback)(void* context); |
86 | |
87 | // A callback function to run after the minidump has been written. |
88 | // |descriptor| contains the file descriptor or file path containing the |
89 | // minidump. |context| is the parameter supplied by the user as |
90 | // callback_context when the handler was created. |succeeded| indicates |
91 | // whether a minidump file was successfully written. |
92 | // |
93 | // If an exception occurred and the callback returns true, Breakpad will |
94 | // treat the exception as fully-handled, suppressing any other handlers from |
95 | // being notified of the exception. If the callback returns false, Breakpad |
96 | // will treat the exception as unhandled, and allow another handler to handle |
97 | // it. If there are no other handlers, Breakpad will report the exception to |
98 | // the system as unhandled, allowing a debugger or native crash dialog the |
99 | // opportunity to handle the exception. Most callback implementations |
100 | // should normally return the value of |succeeded|, or when they wish to |
101 | // not report an exception of handled, false. Callbacks will rarely want to |
102 | // return true directly (unless |succeeded| is true). |
103 | typedef bool (*MinidumpCallback)(const MinidumpDescriptor& descriptor, |
104 | void* context, |
105 | bool succeeded); |
106 | |
107 | // In certain cases, a user may wish to handle the generation of the minidump |
108 | // themselves. In this case, they can install a handler callback which is |
109 | // called when a crash has occurred. If this function returns true, no other |
110 | // processing of occurs and the process will shortly be crashed. If this |
111 | // returns false, the normal processing continues. |
112 | typedef bool (*HandlerCallback)(const void* crash_context, |
113 | size_t crash_context_size, |
114 | void* context); |
115 | |
116 | // Creates a new ExceptionHandler instance to handle writing minidumps. |
117 | // Before writing a minidump, the optional |filter| callback will be called. |
118 | // Its return value determines whether or not Breakpad should write a |
119 | // minidump. The minidump content will be written to the file path or file |
120 | // descriptor from |descriptor|, and the optional |callback| is called after |
121 | // writing the dump file, as described above. |
122 | // If install_handler is true, then a minidump will be written whenever |
123 | // an unhandled exception occurs. If it is false, minidumps will only |
124 | // be written when WriteMinidump is called. |
125 | // If |server_fd| is valid, the minidump is generated out-of-process. If it |
126 | // is -1, in-process generation will always be used. |
127 | ExceptionHandler(const MinidumpDescriptor& descriptor, |
128 | FilterCallback filter, |
129 | MinidumpCallback callback, |
130 | void* callback_context, |
131 | bool install_handler, |
132 | const int server_fd); |
133 | ~ExceptionHandler(); |
134 | |
135 | const MinidumpDescriptor& minidump_descriptor() const { |
136 | return minidump_descriptor_; |
137 | } |
138 | |
139 | void set_minidump_descriptor(const MinidumpDescriptor& descriptor) { |
140 | minidump_descriptor_ = descriptor; |
141 | } |
142 | |
143 | void set_crash_handler(HandlerCallback callback) { |
144 | crash_handler_ = callback; |
145 | } |
146 | |
147 | void set_crash_generation_client(CrashGenerationClient* client) { |
148 | crash_generation_client_.reset(client); |
149 | } |
150 | |
151 | // Writes a minidump immediately. This can be used to capture the execution |
152 | // state independently of a crash. |
153 | // Returns true on success. |
154 | // If the ExceptionHandler has been created with a path, a new file is |
155 | // generated for each minidump. The file path can be retrieved in the |
156 | // MinidumpDescriptor passed to the MinidumpCallback or by accessing the |
157 | // MinidumpDescriptor directly from the ExceptionHandler (with |
158 | // minidump_descriptor()). |
159 | // If the ExceptionHandler has been created with a file descriptor, the file |
160 | // descriptor is repositioned to its beginning and the previous generated |
161 | // minidump is overwritten. |
162 | // Note that this method is not supposed to be called from a compromised |
163 | // context as it uses the heap. |
164 | bool WriteMinidump(); |
165 | |
166 | // Convenience form of WriteMinidump which does not require an |
167 | // ExceptionHandler instance. |
168 | static bool WriteMinidump(const string& dump_path, |
169 | MinidumpCallback callback, |
170 | void* callback_context); |
171 | |
172 | // Write a minidump of |child| immediately. This can be used to |
173 | // capture the execution state of |child| independently of a crash. |
174 | // Pass a meaningful |child_blamed_thread| to make that thread in |
175 | // the child process the one from which a crash signature is |
176 | // extracted. |
177 | // |
178 | // WARNING: the return of this function *must* happen before |
179 | // the code that will eventually reap |child| executes. |
180 | // Otherwise there's a pernicious race condition in which |child| |
181 | // exits, is reaped, another process created with its pid, then that |
182 | // new process dumped. |
183 | static bool WriteMinidumpForChild(pid_t child, |
184 | pid_t child_blamed_thread, |
185 | const string& dump_path, |
186 | MinidumpCallback callback, |
187 | void* callback_context); |
188 | |
189 | // This structure is passed to minidump_writer.h:WriteMinidump via an opaque |
190 | // blob. It shouldn't be needed in any user code. |
191 | struct CrashContext { |
192 | siginfo_t siginfo; |
193 | pid_t tid; // the crashing thread. |
194 | ucontext_t context; |
195 | #if !defined(__ARM_EABI__) && !defined(__mips__) |
196 | // #ifdef this out because FP state is not part of user ABI for Linux ARM. |
197 | // In case of MIPS Linux FP state is already part of ucontext_t so |
198 | // 'float_state' is not required. |
199 | fpstate_t float_state; |
200 | #endif |
201 | }; |
202 | |
203 | // Returns whether out-of-process dump generation is used or not. |
204 | bool IsOutOfProcess() const { |
205 | return crash_generation_client_.get() != NULL; |
206 | } |
207 | |
208 | // Add information about a memory mapping. This can be used if |
209 | // a custom library loader is used that maps things in a way |
210 | // that the linux dumper can't handle by reading the maps file. |
211 | void AddMappingInfo(const string& name, |
212 | const uint8_t identifier[sizeof(MDGUID)], |
213 | uintptr_t start_address, |
214 | size_t mapping_size, |
215 | size_t file_offset); |
216 | |
217 | // Register a block of memory of length bytes starting at address ptr |
218 | // to be copied to the minidump when a crash happens. |
219 | void RegisterAppMemory(void* ptr, size_t length); |
220 | |
221 | // Unregister a block of memory that was registered with RegisterAppMemory. |
222 | void UnregisterAppMemory(void* ptr); |
223 | |
224 | // Force signal handling for the specified signal. |
225 | bool SimulateSignalDelivery(int sig); |
226 | |
227 | // Report a crash signal from an SA_SIGINFO signal handler. |
228 | bool HandleSignal(int sig, siginfo_t* info, void* uc); |
229 | |
230 | private: |
231 | // Save the old signal handlers and install new ones. |
232 | static bool InstallHandlersLocked(); |
233 | // Restore the old signal handlers. |
234 | static void RestoreHandlersLocked(); |
235 | |
236 | void PreresolveSymbols(); |
237 | bool GenerateDump(CrashContext* context); |
238 | void SendContinueSignalToChild(); |
239 | void WaitForContinueSignal(); |
240 | |
241 | static void SignalHandler(int sig, siginfo_t* info, void* uc); |
242 | static int ThreadEntry(void* arg); |
243 | bool DoDump(pid_t crashing_process, const void* context, |
244 | size_t context_size); |
245 | |
246 | const FilterCallback filter_; |
247 | const MinidumpCallback callback_; |
248 | void* const callback_context_; |
249 | |
250 | scoped_ptr<CrashGenerationClient> crash_generation_client_; |
251 | |
252 | MinidumpDescriptor minidump_descriptor_; |
253 | |
254 | // Must be volatile. The compiler is unaware of the code which runs in |
255 | // the signal handler which reads this variable. Without volatile the |
256 | // compiler is free to optimise away writes to this variable which it |
257 | // believes are never read. |
258 | volatile HandlerCallback crash_handler_; |
259 | |
260 | // We need to explicitly enable ptrace of parent processes on some |
261 | // kernels, but we need to know the PID of the cloned process before we |
262 | // can do this. We create a pipe which we can use to block the |
263 | // cloned process after creating it, until we have explicitly enabled |
264 | // ptrace. This is used to store the file descriptors for the pipe |
265 | int fdes[2] = {-1, -1}; |
266 | |
267 | // Callers can add extra info about mappings for cases where the |
268 | // dumper code cannot extract enough information from /proc/<pid>/maps. |
269 | MappingList mapping_list_; |
270 | |
271 | // Callers can request additional memory regions to be included in |
272 | // the dump. |
273 | AppMemoryList app_memory_list_; |
274 | }; |
275 | |
276 | typedef bool (*FirstChanceHandler)(int, siginfo_t*, void*); |
277 | void SetFirstChanceExceptionHandler(FirstChanceHandler callback); |
278 | |
279 | } // namespace google_breakpad |
280 | |
281 | #endif // CLIENT_LINUX_HANDLER_EXCEPTION_HANDLER_H_ |
282 | |