| @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. 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. |
| |
| @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}. |
| |
| There are two versions of @samp{struct _reent}, a normal one and one |
| for small memory systems, controlled by the @code{_REENT_SMALL} |
| definition from the (automatically included) @file{<sys/config.h>}. |
| |
| @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 |
| |
| @ifset STDIO64 |
| @exdent @emph{Additional 64-bit I/O System functions:} |
| _fstat64_r _lseek64_r _open64_r |
| @end ifset |
| |
| @exdent @emph{Time function:} |
| _asctime_r |
| @end example |