visus
/
toolchain-gcc-arm-embedded

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Reentrancy (The Red Hat newlib C Library)</title>

<meta name="description" content="Reentrancy (The Red Hat newlib C Library)">
<meta name="keywords" content="Reentrancy (The Red Hat newlib C Library)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Document-Index.html#Document-Index" rel="index" title="Document Index">
<link href="Document-Index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Misc.html#Misc" rel="next" title="Misc">
<link href="setlocale.html#setlocale" rel="prev" title="setlocale">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Reentrancy"></a>
<div class="header">
<p>
Next: <a href="Misc.html#Misc" accesskey="n" rel="next">Misc</a>, Previous: <a href="Locale.html#Locale" accesskey="p" rel="prev">Locale</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="Document-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Document-Index.html#Document-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Reentrancy-1"></a>
<h2 class="chapter">10 Reentrancy</h2>

<a name="index-reentrancy"></a>
<p>Reentrancy is a characteristic of library functions which allows multiple
processes to use the same address space with assurance that the values stored
in those spaces will remain constant between calls. The Red Hat
newlib implementation of the library functions ensures that 
whenever possible, these library functions are reentrant.  However,
there are some functions that can not be trivially made reentrant.
Hooks have been provided to allow you to use these functions in a fully
reentrant fashion.
</p>
<a name="index-_005freent"></a>
<a name="index-reent_002eh"></a>
<a name="index-reentrancy-structure"></a>
<p>These hooks use the structure <code>_reent</code> defined in <samp>reent.h</samp>.
A variable defined as &lsquo;<samp>struct _reent</samp>&rsquo; is called a <em>reentrancy
structure</em>.  All functions which must manipulate global information are
available in two versions.  The first version has the usual name, and
uses a single global instance of the reentrancy structure.  The second
has a different name, normally formed by prepending &lsquo;<samp>_</samp>&rsquo; and
appending &lsquo;<samp>_r</samp>&rsquo;, and takes a pointer to the particular reentrancy
structure to use.
</p>
<p>For example, the function <code>fopen</code> takes two arguments, <var>file</var>
and <var>mode</var>, and uses the global reentrancy structure.  The function
<code>_fopen_r</code> takes the arguments, <var>struct_reent</var>, which is a
pointer to an instance of the reentrancy structure, <var>file</var>
and <var>mode</var>.	
</p>
<p>There are two versions of &lsquo;<samp>struct _reent</samp>&rsquo;, a normal one and one
for small memory systems, controlled by the <code>_REENT_SMALL</code>
definition from the (automatically included) <samp>&lt;sys/config.h&gt;</samp>.
</p>
<a name="index-global-reentrancy-structure"></a>
<a name="index-_005fimpure_005fptr"></a>
<p>Each function which uses the global reentrancy structure uses the global
variable <code>_impure_ptr</code>, which points to a reentrancy structure.
</p>
<p>This means that you have two ways to achieve reentrancy.  Both require
that each thread of execution control initialize a unique global
variable of type &lsquo;<samp>struct _reent</samp>&rsquo;:
</p>
<ol>
<li> <a name="index-extra-argument_002c-reentrant-fns"></a>
Use the reentrant versions of the library functions, after initializing
a global reentrancy structure for each process.  Use the pointer to this
structure as the extra argument for all library functions.

</li><li> Ensure that each thread of execution control has a pointer to its own
unique reentrancy structure in the global variable <code>_impure_ptr</code>,
and call the standard library subroutines.
</li></ol>

<a name="index-list-of-reentrant-functions"></a>
<a name="index-reentrant-function-list"></a>
<p>The following functions are provided in both reentrant
and non-reentrant versions.
</p>
<div class="example">
<pre class="example"><em>Equivalent for errno variable:</em>
</pre><pre class="example">_errno_r

</pre><pre class="example"><em>Locale functions:</em>
</pre><pre class="example">_localeconv_r  _setlocale_r

</pre><pre class="example"><em>Equivalents for stdio variables:</em>
</pre><pre class="example">_stdin_r        _stdout_r       _stderr_r

</pre><pre class="example"><em>Stdio functions:</em>
</pre><pre class="example">_fdopen_r       _perror_r       _tempnam_r
_fopen_r        _putchar_r      _tmpnam_r
_getchar_r      _puts_r         _tmpfile_r
_gets_r         _remove_r       _vfprintf_r
_iprintf_r      _rename_r       _vsnprintf_r
_mkstemp_r      _snprintf_r     _vsprintf_r
_mktemp_t       _sprintf_r

</pre><pre class="example"><em>Signal functions:</em>
</pre><pre class="example">_init_signal_r  _signal_r
_kill_r         __sigtramp_r
_raise_r

</pre><pre class="example"><em>Stdlib functions:</em>
</pre><pre class="example">_calloc_r       _mblen_r        _setenv_r
_dtoa_r         _mbstowcs_r     _srand_r
_free_r         _mbtowc_r       _strtod_r
_getenv_r       _memalign_r     _strtol_r
_mallinfo_r     _mstats_r       _strtoul_r
_malloc_r       _putenv_r       _system_r
_malloc_r       _rand_r         _wcstombs_r
_malloc_stats_r _realloc_r      _wctomb_r

</pre><pre class="example"><em>String functions:</em>
</pre><pre class="example">_strdup_r       _strtok_r

</pre><pre class="example"><em>System functions:</em>
</pre><pre class="example">_close_r        _link_r         _unlink_r
_execve_r       _lseek_r        _wait_r
_fcntl_r        _open_r         _write_r 
_fork_r         _read_r
_fstat_r        _sbrk_r
_gettimeofday_r _stat_r
_getpid_r       _times_r


</pre><pre class="example"><em>Time function:</em>
</pre><pre class="example">_asctime_r
</pre></div>
<hr>
<div class="header">
<p>
Next: <a href="Misc.html#Misc" accesskey="n" rel="next">Misc</a>, Previous: <a href="Locale.html#Locale" accesskey="p" rel="prev">Locale</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="Document-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Document-Index.html#Document-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>