diff options
Diffstat (limited to 'newlib/libc/reent/reent.tex')
| -rw-r--r-- | newlib/libc/reent/reent.tex | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/newlib/libc/reent/reent.tex b/newlib/libc/reent/reent.tex new file mode 100644 index 00000000000..71a0a0dcdc9 --- /dev/null +++ b/newlib/libc/reent/reent.tex @@ -0,0 +1,108 @@ +@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 _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 + +@exdent @emph{Signal functions:} +_init_signal_r _signal_r +_kill_r __sigtramp_r +_raise_r + +@exdent @emph{Stdlib functions:} +_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 + +@exdent @emph{String functions:} +_strdup_r _strtok_r + +@exdent @emph{System functions:} +_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 + +@exdent @emph{Time function:} +_asctime_r +@end example |