RONCC
/
HPC-Tools-for-Quantum-Computing


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
							<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <meta name="description" content="API documentation for the Rust `backtrace` crate.">
    <meta name="keywords" content="rust, rustlang, rust-lang, backtrace">

    <title>backtrace - Rust</title>

    <link rel="stylesheet" type="text/css" href="../normalize.css">
    <link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle">
    
    <link rel="stylesheet" type="text/css" href="../dark.css">
    <link rel="stylesheet" type="text/css" href="../main.css" id="themeStyle">
    <script src="../storage.js"></script>
    

    
    
</head>
<body class="rustdoc mod">
    <!--[if lte IE 8]>

    <div class="warning">

        This old browser is unsupported and will most likely display funky

        things.

    </div>

    <![endif]-->

    

    <nav class="sidebar">
        <div class="sidebar-menu">&#9776;</div>
        
        <p class='location'>Crate backtrace</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'backtrace', ty: 'mod', relpath: '../'};</script></div>
    </nav>

    <div class="theme-picker">
        <button id="theme-picker" aria-label="Pick another theme!">
            <img src="../brush.svg" width="18" alt="Pick another theme!">
        </button>
        <div id="theme-choices"></div>
    </div>
    <script src="../theme.js"></script>
    <nav class="sub">
        <form class="search-form js-only">
            <div class="search-container">
                <input class="search-input" name="search"

                       autocomplete="off"

                       placeholder="Click or press ‘S’ to search, ‘?’ for more options…"

                       type="search">
            </div>
        </form>
    </nav>

    <section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>backtrace</a></span><span class='out-of-band'><span id='render-detail'>
                   <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                       [<span class='inner'>&#x2212;</span>]
                   </a>
               </span><a class='srclink' href='../src/backtrace/lib.rs.html#1-177' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>A library for acquiring a backtrace at runtime</p>
<p>This library is meant to supplement the <code>RUST_BACKTRACE=1</code> support of the
standard library by allowing an acquisition of a backtrace at runtime
programmatically. The backtraces generated by this library do not need to be
parsed, for example, and expose the functionality of multiple backend
implementations.</p>
<h1 id="implementation" class="section-header"><a href="#implementation">Implementation</a></h1>
<p>This library makes use of a number of strategies for actually acquiring a
backtrace. For example unix uses libgcc's libunwind bindings by default to
acquire a backtrace, but coresymbolication or dladdr is used on OSX to
acquire symbol names while linux uses gcc's libbacktrace.</p>
<p>When using the default feature set of this library the &quot;most reasonable&quot; set
of defaults is chosen for the current platform, but the features activated
can also be controlled at a finer granularity.</p>
<h1 id="platform-support" class="section-header"><a href="#platform-support">Platform Support</a></h1>
<p>Currently this library is verified to work on Linux, OSX, and Windows, but
it may work on other platforms as well. Note that the quality of the
backtrace may vary across platforms.</p>
<h1 id="api-principles" class="section-header"><a href="#api-principles">API Principles</a></h1>
<p>This library attempts to be as flexible as possible to accommodate different
backend implementations of acquiring a backtrace. Consequently the currently
exported functions are closure-based as opposed to the likely expected
iterator-based versions. This is done due to limitations of the underlying
APIs used from the system.</p>
<h1 id="usage" class="section-header"><a href="#usage">Usage</a></h1>
<p>First, add this to your Cargo.toml</p>
<pre><code class="language-toml">[dependencies]
backtrace = &quot;0.2&quot;
</code></pre>
<p>Next:</p>

<pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">backtrace</span>;

<span class="kw">fn</span> <span class="ident">main</span>() {
    <span class="ident">backtrace</span>::<span class="ident">trace</span>(<span class="op">|</span><span class="ident">frame</span><span class="op">|</span> {
        <span class="kw">let</span> <span class="ident">ip</span> <span class="op">=</span> <span class="ident">frame</span>.<span class="ident">ip</span>();
        <span class="kw">let</span> <span class="ident">symbol_address</span> <span class="op">=</span> <span class="ident">frame</span>.<span class="ident">symbol_address</span>();

        <span class="comment">// Resolve this instruction pointer to a symbol name</span>
        <span class="ident">backtrace</span>::<span class="ident">resolve</span>(<span class="ident">ip</span>, <span class="op">|</span><span class="ident">symbol</span><span class="op">|</span> {
            <span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">name</span>) <span class="op">=</span> <span class="ident">symbol</span>.<span class="ident">name</span>() {
                <span class="comment">// ...</span>
            }
            <span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">filename</span>) <span class="op">=</span> <span class="ident">symbol</span>.<span class="ident">filename</span>() {
                <span class="comment">// ...</span>
            }
        });

        <span class="bool-val">true</span> <span class="comment">// keep going to the next frame</span>
    });
}</pre>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.Backtrace.html"

                                  title='struct backtrace::Backtrace'>Backtrace</a></td>
                           <td class='docblock-short'>
                                <p>Representation of an owned and self-contained backtrace.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.BacktraceFrame.html"

                                  title='struct backtrace::BacktraceFrame'>BacktraceFrame</a></td>
                           <td class='docblock-short'>
                                <p>Captured version of a frame in a backtrace.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.BacktraceSymbol.html"

                                  title='struct backtrace::BacktraceSymbol'>BacktraceSymbol</a></td>
                           <td class='docblock-short'>
                                <p>Captured version of a symbol in a backtrace.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.Frame.html"

                                  title='struct backtrace::Frame'>Frame</a></td>
                           <td class='docblock-short'>
                                <p>A trait representing one frame of a backtrace, yielded to the <code>trace</code>
function of this crate.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.Symbol.html"

                                  title='struct backtrace::Symbol'>Symbol</a></td>
                           <td class='docblock-short'>
                                <p>A trait representing the resolution of a symbol in a file.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.SymbolName.html"

                                  title='struct backtrace::SymbolName'>SymbolName</a></td>
                           <td class='docblock-short'>
                                <p>A wrapper around a symbol name to provide ergonomic accessors to the
demangled name, the raw bytes, the raw string, etc.</p>

                           </td>
                       </tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="fn" href="fn.resolve.html"

                                  title='fn backtrace::resolve'>resolve</a></td>
                           <td class='docblock-short'>
                                <p>Resolve an address to a symbol, passing the symbol to the specified
closure.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="fn" href="fn.trace.html"

                                  title='fn backtrace::trace'>trace</a></td>
                           <td class='docblock-short'>
                                <p>Inspects the current call-stack, passing all active frames into the closure
provided to calculate a stack trace.</p>

                           </td>
                       </tr></table></section>
    <section id='search' class="content hidden"></section>

    <section class="footer"></section>

    <aside id="help" class="hidden">
        <div>
            <h1 class="hidden">Help</h1>

            <div class="shortcuts">
                <h2>Keyboard Shortcuts</h2>

                <dl>
                    <dt><kbd>?</kbd></dt>
                    <dd>Show this help dialog</dd>
                    <dt><kbd>S</kbd></dt>
                    <dd>Focus the search field</dd>
                    <dt><kbd>↑</kbd></dt>
                    <dd>Move up in search results</dd>
                    <dt><kbd>↓</kbd></dt>
                    <dd>Move down in search results</dd>
                    <dt><kbd>↹</kbd></dt>
                    <dd>Switch tab</dd>
                    <dt><kbd>&#9166;</kbd></dt>
                    <dd>Go to active search result</dd>
                    <dt><kbd>+</kbd></dt>
                    <dd>Expand all sections</dd>
                    <dt><kbd>-</kbd></dt>
                    <dd>Collapse all sections</dd>
                </dl>
            </div>

            <div class="infos">
                <h2>Search Tricks</h2>

                <p>
                    Prefix searches with a type followed by a colon (e.g.
                    <code>fn:</code>) to restrict the search to a given type.
                </p>

                <p>
                    Accepted types are: <code>fn</code>, <code>mod</code>,
                    <code>struct</code>, <code>enum</code>,
                    <code>trait</code>, <code>type</code>, <code>macro</code>,
                    and <code>const</code>.
                </p>

                <p>
                    Search functions by type signature (e.g.
                    <code>vec -> usize</code> or <code>* -> vec</code>)
                </p>
            </div>
        </div>
    </aside>

    

    <script>

        window.rootPath = "../";

        window.currentCrate = "backtrace";

    </script>
    <script src="../main.js"></script>
    <script defer src="../search-index.js"></script>
</body>
</html>