blob: 6f8a60d1cd848e0b5c4d93b5fc38c7a09c265867 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.18"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Crashpad: crashpad::test::ExceptionSwallower Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="crashpad_doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Crashpad
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.18 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespacecrashpad.html">crashpad</a></li><li class="navelem"><a class="el" href="namespacecrashpad_1_1test.html">test</a></li><li class="navelem"><a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html">ExceptionSwallower</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#nested-classes">Classes</a> &#124;
<a href="#pub-static-methods">Static Public Member Functions</a> &#124;
<a href="classcrashpad_1_1test_1_1ExceptionSwallower-members.html">List of all members</a> </div>
<div class="headertitle">
<div class="title">crashpad::test::ExceptionSwallower Class Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>Swallows <code>EXC_CRASH</code> and <code>EXC_CORPSE_NOTIFY</code> exceptions in test child processes.
<a href="classcrashpad_1_1test_1_1ExceptionSwallower.html#details">More...</a></p>
<p><code>#include &quot;test/mac/exception_swallower.h&quot;</code></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower_1_1ExceptionSwallowerThread.html">ExceptionSwallowerThread</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-static-methods"></a>
Static Public Member Functions</h2></td></tr>
<tr class="memitem:af7fdf8f0dca2bb2a34397d58283d3676"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html#af7fdf8f0dca2bb2a34397d58283d3676">SwallowExceptions</a> ()</td></tr>
<tr class="memdesc:af7fdf8f0dca2bb2a34397d58283d3676"><td class="mdescLeft">&#160;</td><td class="mdescRight">In a test child process, arranges to swallow <code>EXC_CRASH</code> and <code>EXC_CORPSE_NOTIFY</code> exceptions. <a href="classcrashpad_1_1test_1_1ExceptionSwallower.html#af7fdf8f0dca2bb2a34397d58283d3676">More...</a><br /></td></tr>
<tr class="separator:af7fdf8f0dca2bb2a34397d58283d3676"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Swallows <code>EXC_CRASH</code> and <code>EXC_CORPSE_NOTIFY</code> exceptions in test child processes. </p>
<p>This class is intended to be used by test code that crashes intentionally.</p>
<p>On macOS, the system’s crash reporter normally saves crash reports for all crashes in test code, by virtue of being set as the <code>EXC_CRASH</code> or <code>EXC_CORPSE_NOTIFY</code> handler. This litters the user’s <code>~/Library/Logs/DiagnosticReports</code> directory and can be time-consuming. Reports generated for code that crashes intentionally have no value, and many Crashpad tests do crash intentionally.</p>
<p>Instantiate an <a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html" title="Swallows EXC_CRASH and EXC_CORPSE_NOTIFY exceptions in test child processes.">ExceptionSwallower</a> object in a parent test process (a process where <code>TEST()</code>, <code>TEST_F()</code>, and <code>TEST_P()</code> execute) to create an exception swallower server running on a dedicated thread. A service mapping for this server will be published with the bootstrap server and made available in the <code>CRASHPAD_EXCEPTION_SWALLOWER_SERVICE</code> environment variable. In a child process, call <a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html#af7fdf8f0dca2bb2a34397d58283d3676" title="In a test child process, arranges to swallow EXC_CRASH and EXC_CORPSE_NOTIFY exceptions.">SwallowExceptions()</a> to look up this service and set it as the <code>EXC_CRASH</code> and <code>EXC_CORPSE_NOTIFY</code> handler. When these exceptions are raised in the child process, they’ll be handled by the exception swallower server, which performs no action but reports that exceptions were successfully handled so that the system’s crash reporter, ReportCrash, will not be invoked.</p>
<p>At most one <a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html" title="Swallows EXC_CRASH and EXC_CORPSE_NOTIFY exceptions in test child processes.">ExceptionSwallower</a> may be instantiated in a process at a time. If <code>CRASHPAD_EXCEPTION_SWALLOWER_SERVICE</code> is already set, <a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html" title="Swallows EXC_CRASH and EXC_CORPSE_NOTIFY exceptions in test child processes.">ExceptionSwallower</a> leaves it in place and takes no additional action.</p>
<p>Crashpad’s <a class="el" href="gtest__death_8h.html#a415e40b4d538d7421e1b0a43ddd3f83e" title="Wraps the gtest ASSERT_DEATH_IF_SUPPORTED() macro to make assertions about death caused by crashes.">ASSERT_DEATH_CRASH()</a>, <a class="el" href="gtest__death_8h.html#a496cb27779b2120a1854e81375e9ae5f" title="Wraps the gtest EXPECT_DEATH_IF_SUPPORTED() macro to make assertions about death caused by crashes.">EXPECT_DEATH_CRASH()</a>, <a class="el" href="gtest__death_8h.html#a11ab1a718cd7a7ed56b7e2fbd2c36f74" title="Wraps the ASSERT_DEATH_CRASH() macro to make assertions about death caused by CHECK() failures.">ASSERT_DEATH_CHECK()</a>, and <a class="el" href="gtest__death_8h.html#aa4bd7e1dbfc8862448a4b0fb66790e50" title="Wraps the EXPECT_DEATH_CRASH() macro to make assertions about death caused by CHECK() failures.">EXPECT_DEATH_CHECK()</a> macros make use of this class on macOS, as does the <a class="el" href="classcrashpad_1_1test_1_1Multiprocess.html" title="Manages a multiprocess test.">Multiprocess</a> test interface. </p>
</div><h2 class="groupheader">Member Function Documentation</h2>
<a id="af7fdf8f0dca2bb2a34397d58283d3676"></a>
<h2 class="memtitle"><span class="permalink"><a href="#af7fdf8f0dca2bb2a34397d58283d3676">&#9670;&nbsp;</a></span>SwallowExceptions()</h2>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">void crashpad::test::ExceptionSwallower::SwallowExceptions </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>In a test child process, arranges to swallow <code>EXC_CRASH</code> and <code>EXC_CORPSE_NOTIFY</code> exceptions. </p>
<p>This must be called in a test child process. It must not be called from a parent test process directly. Parent test processes are those that execute <code>TEST()</code>, <code>TEST_F()</code>, and <code>TEST_P()</code>. Test child processes execute <a class="el" href="gtest__death_8h.html#a415e40b4d538d7421e1b0a43ddd3f83e" title="Wraps the gtest ASSERT_DEATH_IF_SUPPORTED() macro to make assertions about death caused by crashes.">ASSERT_DEATH_CRASH()</a>, <a class="el" href="gtest__death_8h.html#a496cb27779b2120a1854e81375e9ae5f" title="Wraps the gtest EXPECT_DEATH_IF_SUPPORTED() macro to make assertions about death caused by crashes.">EXPECT_DEATH_CRASH()</a>, <a class="el" href="gtest__death_8h.html#a11ab1a718cd7a7ed56b7e2fbd2c36f74" title="Wraps the ASSERT_DEATH_CRASH() macro to make assertions about death caused by CHECK() failures.">ASSERT_DEATH_CHECK()</a>, <a class="el" href="gtest__death_8h.html#aa4bd7e1dbfc8862448a4b0fb66790e50" title="Wraps the EXPECT_DEATH_CRASH() macro to make assertions about death caused by CHECK() failures.">EXPECT_DEATH_CHECK()</a>, and Multiprocess::RunChild().</p>
<p>It is an error to call this in a test child process without having first instantiated an <a class="el" href="classcrashpad_1_1test_1_1ExceptionSwallower.html" title="Swallows EXC_CRASH and EXC_CORPSE_NOTIFY exceptions in test child processes.">ExceptionSwallower</a> object in a parent test project. It is also an error to call this in a parent test process. </p>
</div>
</div>
<hr/>The documentation for this class was generated from the following files:<ul>
<li>test/mac/exception_swallower.h</li>
<li>test/mac/exception_swallower.cc</li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.18
</small></address>
</body>
</html>