mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-27 07:41:28 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/topic/plinth.html
Gareth Rees 6cbd932e05 Updated manual html 
Copied from Perforce
 Change: 182092
 ServerID: perforce.ravenbrook.com
2013-05-22 19:26:41 +01:00

501 lines
No EOL
36 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://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/html; charset=utf-8" />
<title>21. Plinth &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.111.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="22. Platforms" href="platform.html" />
<link rel="prev" title="20. Weak references" href="weak.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="platform.html" title="22. Platforms"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="weak.html" title="20. Weak references"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="plinth">
<span id="topic-plinth"></span><span id="index-0"></span><h1>21. Plinth<a class="headerlink" href="#plinth" title="Permalink to this headline"></a></h1>
<p>The <em class="dfn">plinth</em> is a program module that provides the MPS with the
support it needs from the execution environment. The MPS uses the plinth instead of (say) the Standard C Library because:</p>
<ol class="arabic simple">
<li>The MPS is designed to be portable to systems that have only a
<em>conforming freestanding implementation</em> of the C language: that
is, systems which potentially lack some of the facilities of the
Standard C Library, such as standard I/O. The plinth provides a way
to map MPS requirements to the facilities provided on the platform,
whatever they are.</li>
<li>The plinth gives the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> complete control of
interaction between the MPS and the user, including
<a class="reference internal" href="error.html#topic-error-assertion"><em>assertions</em></a> and <a class="reference internal" href="telemetry.html#topic-telemetry"><em>telemetry</em></a>.</li>
</ol>
<p>The plinth may be provided by the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>; however, a
sample implementation of the plinth using ANSI Standard C Library
facilities is included with the MPS, and this is good enough for most
applications.</p>
<p>There are many reasons why you might want to write your own plinth.
You may be targeting a <em>freestanding environment</em> such as an embedded
system. You might need to write the telemetry stream to a system
logging facility, or transmit it over a serial port or network
connection. Or you might need to direct debugging output to a
convenient window in the user interface.</p>
<p>The plinth is divided into two parts:</p>
<ol class="arabic simple">
<li>The <a class="reference internal" href="#topic-plinth-io"><em>I/O module</em></a> enables the MPS to write binary messages
to an output stream.</li>
<li>The <a class="reference internal" href="#topic-plinth-lib"><em>Library module</em></a> provides miscellaneous functionality
that would be available via the Standard C Library on a hosted
platform, including functions for reporting errors and accessing
a processor clock.</li>
</ol>
<dl class="macro">
<dt id="CONFIG_PLINTH_NONE">
<tt class="descname">CONFIG_PLINTH_NONE</tt><a class="headerlink" href="#CONFIG_PLINTH_NONE" title="Permalink to this definition"></a></dt>
<dd><p>If this preprocessor constant is defined, exclude the ANSI plinth
(<tt class="docutils literal"><span class="pre">mpsioan.c</span></tt> and <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>) from the MPS. For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">DCONFIG_PLINTH_NONE</span> <span class="o">-</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Unix</span><span class="o">/</span><span class="n">OS</span> <span class="n">X</span><span class="p">)</span>
<span class="n">cl</span> <span class="o">/</span><span class="n">Gs</span> <span class="o">/</span><span class="n">DCONFIG_PLINTH_NONE</span> <span class="o">/</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Windows</span><span class="p">)</span>
</pre></div>
</div>
<p>Having excluded the ANSI plinth, you must of course supply your
own.</p>
</dd></dl>
<div class="section" id="i-o-module">
<span id="topic-plinth-io"></span><span id="index-1"></span><h2>21.1. I/O module<a class="headerlink" href="#i-o-module" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpsio.h&quot;</span>
</pre></div>
</div>
<dl class="type">
<dt id="mps_io_t">
<tt class="descname">mps_io_t</tt><a class="headerlink" href="#mps_io_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the internal state of the I/O module.</p>
<p>This is an alias for a pointer to the incomplete structure
<tt class="xref c c-type docutils literal"><span class="pre">mps_io_s</span></tt>, which the <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> may define if it
needs to. Alternatively, it may leave the structure type undefined
and simply cast its own pointer to and from <a class="reference internal" href="#mps_io_t" title="mps_io_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_io_t</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI I/O module, <tt class="docutils literal"><span class="pre">mpsioan.c</span></tt>, this is an alias for
<tt class="docutils literal"><span class="pre">FILE&nbsp;*</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_io_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_io_create</tt><big>(</big><a class="reference internal" href="#mps_io_t" title="mps_io_t">mps_io_t</a><em>&nbsp;*io_o</em><big>)</big><a class="headerlink" href="#mps_io_create" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function for setting up the I/O module.</p>
<p><tt class="docutils literal"><span class="pre">io_o</span></tt> points to a location which the plinth may update with a
pointer to its internal state, if any.</p>
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if successful.</p>
<p>The MPS calls this function to set up the I/O module, for example
if there are events in the <a class="reference internal" href="../glossary/t.html#term-telemetry-stream"><em class="xref std std-term">telemetry stream</em></a> that need to
be output.</p>
<p>A typical plinth will use it to open a file for writing, or to
connect to the system logging interface.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI I/O module, <tt class="docutils literal"><span class="pre">mpsioan.c</span></tt>, this calls <tt class="docutils literal"><span class="pre">fopen</span></tt> on
the file named by the environment variable
<span class="target" id="index-2"></span><a class="reference internal" href="telemetry.html#envvar-MPS_TELEMETRY_FILENAME"><tt class="xref std std-envvar docutils literal"><span class="pre">MPS_TELEMETRY_FILENAME</span></tt></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_io_destroy">
void <tt class="descname">mps_io_destroy</tt><big>(</big><a class="reference internal" href="#mps_io_t" title="mps_io_t">mps_io_t</a><em>&nbsp;io</em><big>)</big><a class="headerlink" href="#mps_io_destroy" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function for tearing down the I/O module.</p>
<p><tt class="docutils literal"><span class="pre">io</span></tt> is the value that the plinth wrote to <tt class="docutils literal"><span class="pre">io_o</span></tt> when the MPS
called <a class="reference internal" href="#mps_io_create" title="mps_io_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_io_create()</span></tt></a>. If the plinth wrote no value, this
parameter is undefined.</p>
<p>After calling this function, the MPS guarantees not to use the
value <tt class="docutils literal"><span class="pre">io</span></tt> again.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI I/O module, <tt class="docutils literal"><span class="pre">mpsioan.c</span></tt>, this calls <tt class="docutils literal"><span class="pre">fclose</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_io_write">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_io_write</tt><big>(</big><a class="reference internal" href="#mps_io_t" title="mps_io_t">mps_io_t</a><em>&nbsp;io</em>, void<em>&nbsp;*buf</em>, size_t<em>&nbsp;size</em><big>)</big><a class="headerlink" href="#mps_io_write" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function for writing data via the I/O module.</p>
<p><tt class="docutils literal"><span class="pre">io</span></tt> is the value that the plinth wrote to <tt class="docutils literal"><span class="pre">io_o</span></tt> when the MPS
called <a class="reference internal" href="#mps_io_create" title="mps_io_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_io_create()</span></tt></a>. If the plinth wrote no value, this
parameter is undefined.</p>
<p><tt class="docutils literal"><span class="pre">buf</span></tt> points to the data to write.</p>
<p><tt class="docutils literal"><span class="pre">size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of the data in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>.</p>
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if successful.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI I/O module, <tt class="docutils literal"><span class="pre">mpsioan.c</span></tt>, this calls <tt class="docutils literal"><span class="pre">fwrite</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_io_flush">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_io_flush</tt><big>(</big><a class="reference internal" href="#mps_io_t" title="mps_io_t">mps_io_t</a><em>&nbsp;io</em><big>)</big><a class="headerlink" href="#mps_io_flush" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function for flushing the I/O module.</p>
<p><tt class="docutils literal"><span class="pre">io</span></tt> is the value that the plinth wrote to <tt class="docutils literal"><span class="pre">io_o</span></tt> when the MPS
called <a class="reference internal" href="#mps_io_create" title="mps_io_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_io_create()</span></tt></a>. If the plinth wrote no value, this
parameter is undefined.</p>
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if successful.</p>
<p>The MPS calls this function when it is done with the
<a class="reference internal" href="../glossary/t.html#term-telemetry-stream"><em class="xref std std-term">telemetry stream</em></a>, or when the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> calls
<a class="reference internal" href="telemetry.html#mps_telemetry_flush" title="mps_telemetry_flush"><tt class="xref c c-func docutils literal"><span class="pre">mps_telemetry_flush()</span></tt></a>. This function should ensure that
the buffers of data passed to the latest calls to
<a class="reference internal" href="#mps_io_write" title="mps_io_write"><tt class="xref c c-func docutils literal"><span class="pre">mps_io_write()</span></tt></a> are properly recorded, should the
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> terminate (uncontrollably as a result of a
bug, for example) or some interactive tool require access to the
event data.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI I/O module, <tt class="docutils literal"><span class="pre">mpsioan.c</span></tt>, this calls <tt class="docutils literal"><span class="pre">fflush</span></tt>.</p>
</div>
</dd></dl>
</div>
<div class="section" id="library-module">
<span id="topic-plinth-lib"></span><span id="index-3"></span><h2>21.2. Library module<a class="headerlink" href="#library-module" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpslib.h&quot;</span>
</pre></div>
</div>
<dl class="function">
<dt id="mps_clock">
<a class="reference internal" href="interface.html#mps_clock_t" title="mps_clock_t">mps_clock_t</a> <tt class="descname">mps_clock</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_clock" title="Permalink to this definition"></a></dt>
<dd><p>Return the time since some epoch, in units given by
<a class="reference internal" href="#mps_clocks_per_sec" title="mps_clocks_per_sec"><tt class="xref c c-func docutils literal"><span class="pre">mps_clocks_per_sec()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, calls <tt class="docutils literal"><span class="pre">clock</span></tt>.</p>
</div>
<p>The MPS calls this function to make scheduling decisions (see
<a class="reference internal" href="collection.html#topic-collection-schedule"><em>Scheduling of collections</em></a>), and to calibrate the time
stamps on events in the <a class="reference internal" href="../glossary/t.html#term-telemetry-stream"><em class="xref std std-term">telemetry stream</em></a>. If your platform
has a low-resolution <tt class="docutils literal"><span class="pre">clock()</span></tt>, and there are higher-resolution
clocks readily available, then using one of those will improve MPS
scheduling decisions and the quality of telemetry output. For
instance, with <tt class="docutils literal"><span class="pre">getrusage()</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &lt;sys/resource.h&gt;</span>
<span class="n">mps_clock_t</span> <span class="nf">mps_clock</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="k">struct</span> <span class="n">rusage</span> <span class="n">s</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">res</span> <span class="o">=</span> <span class="n">getrusage</span><span class="p">(</span><span class="n">RUSAGE_SELF</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">s</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* handle error */</span>
<span class="p">}</span>
<span class="k">return</span> <span class="p">((</span><span class="n">mps_clock_t</span><span class="p">)</span><span class="n">s</span><span class="p">.</span><span class="n">ru_utime</span><span class="p">.</span><span class="n">tv_sec</span><span class="p">)</span> <span class="o">*</span> <span class="mi">1000000</span> <span class="o">+</span> <span class="n">s</span><span class="p">.</span><span class="n">ru_utime</span><span class="p">.</span><span class="n">tv_usec</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_clocks_per_sec">
<a class="reference internal" href="interface.html#mps_clock_t" title="mps_clock_t">mps_clock_t</a> <tt class="descname">mps_clocks_per_sec</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_clocks_per_sec" title="Permalink to this definition"></a></dt>
<dd><p>Return the number of clock units per second, as returned by
<a class="reference internal" href="#mps_clock" title="mps_clock"><tt class="xref c c-func docutils literal"><span class="pre">mps_clock()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, returns
<tt class="docutils literal"><span class="pre">CLOCKS_PER_SEC</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_assert_fail">
void <tt class="descname">mps_lib_assert_fail</tt><big>(</big>const char<em>&nbsp;*message</em><big>)</big><a class="headerlink" href="#mps_lib_assert_fail" title="Permalink to this definition"></a></dt>
<dd><p>Report an assertion failure and abort.</p>
<p><tt class="docutils literal"><span class="pre">message</span></tt> is a NUL-terminated string describing the assertion
failure.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this reports the
failure using <tt class="docutils literal"><span class="pre">fprintf(stderr,</span> <span class="pre">&quot;...%s...&quot;,</span> <span class="pre">message)</span></tt> and
terminates the program by calling <tt class="docutils literal"><span class="pre">abort</span></tt>.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_lib_FILE">
<tt class="descname">mps_lib_FILE</tt><a class="headerlink" href="#mps_lib_FILE" title="Permalink to this definition"></a></dt>
<dd><p>The type of output streams provided by the plinth.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this is an alias
for <tt class="docutils literal"><span class="pre">FILE&nbsp;*</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_fputc">
int <tt class="descname">mps_lib_fputc</tt><big>(</big>int<em>&nbsp;c</em>, <a class="reference internal" href="#mps_lib_FILE" title="mps_lib_FILE">mps_lib_FILE</a><em>&nbsp;*stream</em><big>)</big><a class="headerlink" href="#mps_lib_fputc" title="Permalink to this definition"></a></dt>
<dd><p>Write a character to an output stream.</p>
<p><tt class="docutils literal"><span class="pre">c</span></tt> is the character.</p>
<p><tt class="docutils literal"><span class="pre">stream</span></tt> is the stream.</p>
<p>Return the character written if successful, or
<a class="reference internal" href="#mps_lib_get_EOF" title="mps_lib_get_EOF"><tt class="xref c c-func docutils literal"><span class="pre">mps_lib_get_EOF()</span></tt></a> if not.</p>
<p>This function is intended to have the same semantics as the
<tt class="docutils literal"><span class="pre">fputc</span></tt> function of the ANSI C Standard (<a class="reference internal" href="../mmref/bib.html#iso90"><em>ISO/IEC 9899:1990</em></a> §7.11.7.3).</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this is a simple
wrapper around <tt class="docutils literal"><span class="pre">fputc</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_fputs">
int <tt class="descname">mps_lib_fputs</tt><big>(</big>const char<em>&nbsp;*s</em>, <a class="reference internal" href="#mps_lib_FILE" title="mps_lib_FILE">mps_lib_FILE</a><em>&nbsp;*stream</em><big>)</big><a class="headerlink" href="#mps_lib_fputs" title="Permalink to this definition"></a></dt>
<dd><p>Write a string to an output stream.</p>
<p><tt class="docutils literal"><span class="pre">s</span></tt> is the NUL-terminated string.</p>
<p><tt class="docutils literal"><span class="pre">stream</span></tt> is the stream.</p>
<p>This function is intended to have the same semantics as the
<tt class="docutils literal"><span class="pre">fputs</span></tt> function of the ANSI C Standard (<a class="reference internal" href="../mmref/bib.html#iso90"><em>ISO/IEC 9899:1990</em></a> §7.11.7.4).</p>
<p>Return a non-negative integer if successful, or
<a class="reference internal" href="#mps_lib_get_EOF" title="mps_lib_get_EOF"><tt class="xref c c-func docutils literal"><span class="pre">mps_lib_get_EOF()</span></tt></a> if not.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this is a simple
wrapper around <tt class="docutils literal"><span class="pre">fputs</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_get_EOF">
int <tt class="descname">mps_lib_get_EOF</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_lib_get_EOF" title="Permalink to this definition"></a></dt>
<dd><p>Return the value that is returned from <a class="reference internal" href="#mps_lib_fputc" title="mps_lib_fputc"><tt class="xref c c-func docutils literal"><span class="pre">mps_lib_fputc()</span></tt></a> and
<a class="reference internal" href="#mps_lib_fputs" title="mps_lib_fputs"><tt class="xref c c-func docutils literal"><span class="pre">mps_lib_fputs()</span></tt></a> to indicate failure.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this returns
<tt class="docutils literal"><span class="pre">EOF</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_get_stderr">
<a class="reference internal" href="#mps_lib_FILE" title="mps_lib_FILE">mps_lib_FILE</a> *<tt class="descname">mps_lib_get_stderr</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_lib_get_stderr" title="Permalink to this definition"></a></dt>
<dd><p>Returns an output stream suitable for reporting errors.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this returns
<tt class="docutils literal"><span class="pre">stderr</span></tt>.</p>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The MPS does not use this at present, but it may be required
in future.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_get_stdout">
<a class="reference internal" href="#mps_lib_FILE" title="mps_lib_FILE">mps_lib_FILE</a> *<tt class="descname">mps_lib_get_stdout</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_lib_get_stdout" title="Permalink to this definition"></a></dt>
<dd><p>Returns an output stream suitable for reporting informative
output.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this returns
<tt class="docutils literal"><span class="pre">stdout</span></tt>.</p>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The MPS does not use this at present, but it may be required
in future.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_memcmp">
int <tt class="descname">mps_lib_memcmp</tt><big>(</big>const void<em>&nbsp;*s1</em>, const void<em>&nbsp;*s2</em>, size_t<em>&nbsp;n</em><big>)</big><a class="headerlink" href="#mps_lib_memcmp" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function similar to the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
function <tt class="docutils literal"><span class="pre">memcmp</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">s1</span></tt> and <tt class="docutils literal"><span class="pre">s2</span></tt> point to <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">blocks</em></a> of memory to be
compared.</p>
<p><tt class="docutils literal"><span class="pre">n</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of the blocks.</p>
<p>Returns an integer that is greater than, equal to, or less than
zero, accordingly as the block pointed to by <tt class="docutils literal"><span class="pre">s1</span></tt> is greater than,
equal to, or less than the block pointed to by <tt class="docutils literal"><span class="pre">s2</span></tt>.</p>
<p>This function is intended to have the same semantics as the
<tt class="docutils literal"><span class="pre">memcmp</span></tt> function of the ANSI C Standard (<a class="reference internal" href="../mmref/bib.html#iso90"><em>ISO/IEC
9899:1990</em></a> §7.11.4.1).</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this is a simple
wrapper around <tt class="docutils literal"><span class="pre">memcmp</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_memcpy">
void *<tt class="descname">mps_lib_memcpy</tt><big>(</big>void<em>&nbsp;*dest</em>, const void<em>&nbsp;*source</em>, size_t<em>&nbsp;n</em><big>)</big><a class="headerlink" href="#mps_lib_memcpy" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function similar to the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
function <tt class="docutils literal"><span class="pre">memcpy</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">dest</span></tt> points to the destination.</p>
<p><tt class="docutils literal"><span class="pre">source</span></tt> points to the source.</p>
<p><tt class="docutils literal"><span class="pre">n</span></tt> is the number of bytes to copy from <tt class="docutils literal"><span class="pre">source</span></tt> to <tt class="docutils literal"><span class="pre">dest</span></tt>.</p>
<p>Returns <tt class="docutils literal"><span class="pre">dest</span></tt>.</p>
<p>This function is intended to have the same semantics as the
<tt class="docutils literal"><span class="pre">memcpy</span></tt> function of the ANSI C Standard (<a class="reference internal" href="../mmref/bib.html#iso90"><em>ISO/IEC
9899:1990</em></a> §7.11.2.1).</p>
<p>The MPS never passes overlapping blocks to
<a class="reference internal" href="#mps_lib_memcpy" title="mps_lib_memcpy"><tt class="xref c c-func docutils literal"><span class="pre">mps_lib_memcpy()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this is a simple
wrapper around <tt class="docutils literal"><span class="pre">memcpy</span></tt>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_memset">
void *<tt class="descname">mps_lib_memset</tt><big>(</big>void<em>&nbsp;*s</em>, int<em>&nbsp;c</em>, size_t<em>&nbsp;n</em><big>)</big><a class="headerlink" href="#mps_lib_memset" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function similar to the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
function <tt class="docutils literal"><span class="pre">memset</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">s</span></tt> points to the <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">block</em></a> to fill with the byte <tt class="docutils literal"><span class="pre">c</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">c</span></tt> is the byte to fill with (when converted to <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt>).</p>
<p><tt class="docutils literal"><span class="pre">n</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of the block.</p>
<p>Returns <tt class="docutils literal"><span class="pre">s</span></tt>.</p>
<p>This function is intended to have the same semantics as the
<tt class="docutils literal"><span class="pre">memset</span></tt> function of the ANSI C Standard (<a class="reference internal" href="../mmref/bib.html#iso90"><em>ISO/IEC
9899:1990</em></a> §7.11.6.1).</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this is a simple
wrapper around <tt class="docutils literal"><span class="pre">memset</span></tt>.</p>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The MPS does not use this at present, but it may be required
in future.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_lib_telemetry_control">
unsigned long <tt class="descname">mps_lib_telemetry_control</tt><big>(</big><big>)</big><a class="headerlink" href="#mps_lib_telemetry_control" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function to supply a default value for the
<a class="reference internal" href="../glossary/t.html#term-telemetry-filter"><em class="xref std std-term">telemetry filter</em></a> from the environment. See
<a class="reference internal" href="telemetry.html#mps_telemetry_control" title="mps_telemetry_control"><tt class="xref c c-func docutils literal"><span class="pre">mps_telemetry_control()</span></tt></a> for more information on the
significant of the value.</p>
<p>Returns the default value of the telemetry filter, as derived from
the environment. It is recommended that the environment be
consulted for a symbol analogous to
<span class="target" id="index-4"></span><a class="reference internal" href="telemetry.html#envvar-MPS_TELEMETRY_CONTROL"><tt class="xref std std-envvar docutils literal"><span class="pre">MPS_TELEMETRY_CONTROL</span></tt></a>, subject to local restrictions.</p>
<p>In the absence of environmental data, a default of zero is
recommended.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In the ANSI Library module, <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>, this reads the
environment variable <span class="target" id="index-5"></span><a class="reference internal" href="telemetry.html#envvar-MPS_TELEMETRY_CONTROL"><tt class="xref std std-envvar docutils literal"><span class="pre">MPS_TELEMETRY_CONTROL</span></tt></a>.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">21. Plinth</a><ul>
<li><a class="reference internal" href="#i-o-module">21.1. I/O module</a></li>
<li><a class="reference internal" href="#library-module">21.2. Library module</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="weak.html"
title="previous chapter">20. Weak references</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="platform.html"
title="next chapter">22. Platforms</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
<a href="http://www.ravenbrook.com/project/mps/release/">All MPS Kit releases</a>
</p>
<h4>Issues</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/issue/?action=list&amp;view=status%3dopen&amp;display=Job:Priority:Title&amp;sort=Priority">Known issues</a><br>
<a href="http://www.ravenbrook.com/project/mps/issue/?action=fixed&release_fixed=1.111.0">Issues fixed in release 1.111.0</a>
</p><h4>Contact us</h4>
<p class="topless"><a href="mailto:mps-questions@ravenbrook.com">mps-questions@ravenbrook.com</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="platform.html" title="22. Platforms"
>next</a> |</li>
<li class="right" >
<a href="weak.html" title="20. Weak references"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2013, Ravenbrook Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink