<!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" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.18.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>mi-malloc: Guarded Mode</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="codefolding.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.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="mimalloc-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 id="projectrow">
<td id="projectlogo"><img alt="Logo" src="mimalloc-logo.svg"/></td>
<td id="projectalign">
<div id="projectname">mi-malloc<span id="projectnumber"> 3.6/2.5/1.15</span>
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" class="search-icon"><span class="search-icon-dropdown"></span></span>
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><div id="MSearchCloseImg" class="close-icon"></div></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.18.0 -->
<script type="text/javascript">
let searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', codefold.init);
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded',() => { initNavTree('guarded.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Guarded Mode </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><em>mimalloc</em> can be built in guarded mode using <span class="tt">-DMI_GUARDED=ON</span> with CMake. This is enabled by default in debug builds. Guarded mode places OS guard pages behind selected allocations to catch buffer overflows as they occur. On hardware supporting <a class="el" href="security.html#memory_tagging" title="memory_tagging">MTE</a>, tagging can detect many such overflows more efficiently.</p>
<p>This can be invaluable to catch buffer-overflow bugs in large programs. However, it also means that any object allocated with a guard page takes at least 8 KiB memory for the guard page and its alignment. As such, allocating a guard page for every allocation may be too expensive both in terms of memory, and in terms of performance with many system calls. Therefore, there are various environment variables (and options) to tune this. When environment options are restricted (see <a class="el" href="security.html#security_environment" title="security_environment">Environment Options</a>), use <a class="el" href="group__options.html#gaf84921c32375e25754dc2ee6a911fa60">mi_option_set()</a> instead.</p>
<ul>
<li><span class="tt">MIMALLOC_GUARDED_SAMPLE_RATE=N</span>: Set the sample rate to <span class="tt">N</span> (by default 0). This mode places a guard page behind a suitable object about every <span class="tt">N</span> requested bytes (per thread). Since the performance in guarded mode without placing guard pages is close to release mode, this can be used to enable guard pages even in production to catch latent buffer overflow bugs, for example with <span class="tt">16KiB</span> or higher for a small performance impact. Set the sample rate to <span class="tt">1</span> to guard every object, and to <span class="tt">0</span> to place no guard pages at all.</li>
<li><span class="tt">MIMALLOC_GUARDED_SAMPLE_SEED=N</span>: Start sampling at <span class="tt">N</span> (by default random). Can be used to reproduce a buffer overflow if needed.</li>
<li><span class="tt">MIMALLOC_GUARDED_MIN=N</span>, <span class="tt">MIMALLOC_GUARDED_MAX=N</span>: Minimal and maximal <em>rounded</em> object sizes for which a guard page is considered (<span class="tt">0</span> and <span class="tt">1GiB</span> respectively). If you suspect a buffer overflow occurs with an object of size 141, set the minimum and maximum to <span class="tt">148</span> and the sample rate to <span class="tt">1</span> to have all of those guarded. </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.18.0 </li>
</ul>
</div>
</body>
</html>