1 files changed, 98 insertions, 0 deletions
diff --git a/newlib/libc/reent/reent.tex b/newlib/libc/reent/reent.tex
new file mode 100644
index 0000000..8ef35f8
--- /dev/null
+++ b/newlib/libc/reent/reent.tex
@@ -0,0 +1,98 @@
+@node Reentrancy
+@chapter Reentrancy
+
+@cindex reentrancy
+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. Cygnus's 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.
+
+@findex _reent
+@findex reent.h
+@cindex reentrancy structure
+These hooks use the structure @code{_reent} defined in @file{reent.h}.
+A variable defined as @samp{struct _reent} is called a @dfn{reentrancy
+structure}.  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 @samp{_} and
+appending @samp{_r}, and takes a pointer to the particular reentrancy
+structure to use.
+
+For example, the function @code{fopen} takes two arguments, @var{file}
+and @var{mode}, and uses the global reentrancy structure.  The function
+@code{_fopen_r} takes the arguments, @var{struct_reent}, which is a
+pointer to an instance of the reentrancy structure, @var{file}
+and @var{mode}.	
+
+@cindex global reentrancy structure
+@findex _impure_ptr
+Each function which uses the global reentrancy structure uses the global
+variable @code{_impure_ptr}, which points to a reentrancy structure.
+
+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 @samp{struct _reent}:
+
+@enumerate
+@item
+@cindex extra argument, reentrant fns
+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.
+
+@item
+Ensure that each thread of execution control has a pointer to its own
+unique reentrancy structure in the global variable @code{_impure_ptr},
+and call the standard library subroutines.
+@end enumerate
+
+@cindex list of reentrant functions
+@cindex reentrant function list
+The following functions are provided in both reentrant
+and non-reentrant versions.
+
+@example
+@exdent @emph{Equivalent for errno variable:}
+_errno_r
+
+@exdent @emph{Locale functions:}
+_localeconv_r  _setlocale_r
+
+@exdent @emph{Equivalents for stdio variables:}
+_stdin_r        _stdout_r       _stderr_r
+
+@page  
+@exdent @emph{Stdio functions:}
+_fdopen_r       _mkstemp_r       _remove_r
+_fopen_r        _mktemp_r        _rename_r
+_getchar_r      _perror_r        _tempnam_r
+_gets_r         _putchar_r       _tmpnam_r 
+_iprintf_r 	_puts_r		 _tmpfile_r
+
+@exdent @emph{Signal functions:}
+_raise_r        _signal_r
+
+@exdent @emph{Stdlib functions:}
+@c FIXME! dtoa undoc; should _dtoa_r be mentioned?
+_dtoa_r         _realloc_r      _strtoul_r
+_free_r         _srand_r        _system_r
+_malloc_r       _strtod_r
+_rand_r         _strtol_r
+
+@exdent @emph{String functions:}
+_strtok_r
+
+@exdent @emph{System functions:}
+_close_r        _lseek_r        _stat_r
+_fork_r         _open_r         _unlink_r
+_fstat_r        _read_r         _wait_r
+_link_r         _sbrk_r         _write_r
+
+@exdent @emph{Time function:}
+_asctime_r
+@end example