newlib/libc/reent/reent.tex

   1 @node Reentrancy
   2 @chapter Reentrancy
   3
   4 @cindex reentrancy
   5 Reentrancy is a characteristic of library functions which allows multiple
   6 processes to use the same address space with assurance that the values stored
   7 in those spaces will remain constant between calls. The Red Hat
   8 newlib implementation of the library functions ensures that
   9 whenever possible, these library functions are reentrant.  However,
  10 there are some functions that can not be trivially made reentrant.
  11 Hooks have been provided to allow you to use these functions in a fully
  12 reentrant fashion.
  13
  14 @findex _reent
  15 @findex reent.h
  16 @cindex reentrancy structure
  17 These hooks use the structure @code{_reent} defined in @file{reent.h}.
  18 A variable defined as @samp{struct _reent} is called a @dfn{reentrancy
  19 structure}.  All functions which must manipulate global information are
  20 available in two versions.  The first version has the usual name, and
  21 uses a single global instance of the reentrancy structure.  The second
  22 has a different name, normally formed by prepending @samp{_} and
  23 appending @samp{_r}, and takes a pointer to the particular reentrancy
  24 structure to use.
  25
  26 For example, the function @code{fopen} takes two arguments, @var{file}
  27 and @var{mode}, and uses the global reentrancy structure.  The function
  28 @code{_fopen_r} takes the arguments, @var{struct_reent}, which is a
  29 pointer to an instance of the reentrancy structure, @var{file}
  30 and @var{mode}.
  31
  32 There are two versions of @samp{struct _reent}, a normal one and one
  33 for small memory systems, controlled by the @code{_REENT_SMALL}
  34 definition from the (automatically included) @file{<sys/config.h>}.
  35
  36 @cindex global reentrancy structure
  37 @findex _impure_ptr
  38 Each function which uses the global reentrancy structure uses the global
  39 variable @code{_impure_ptr}, which points to a reentrancy structure.
  40
  41 This means that you have two ways to achieve reentrancy.  Both require
  42 that each thread of execution control initialize a unique global
  43 variable of type @samp{struct _reent}:
  44
  45 @enumerate
  46 @item
  47 @cindex extra argument, reentrant fns
  48 Use the reentrant versions of the library functions, after initializing
  49 a global reentrancy structure for each process.  Use the pointer to this
  50 structure as the extra argument for all library functions.
  51
  52 @item
  53 Ensure that each thread of execution control has a pointer to its own
  54 unique reentrancy structure in the global variable @code{_impure_ptr},
  55 and call the standard library subroutines.
  56 @end enumerate
  57
  58 @cindex list of reentrant functions
  59 @cindex reentrant function list
  60 The following functions are provided in both reentrant
  61 and non-reentrant versions.
  62
  63 @example
  64 @exdent @emph{Equivalent for errno variable:}
  65 _errno_r
  66
  67 @exdent @emph{Locale functions:}
  68 _localeconv_r  _setlocale_r
  69
  70 @exdent @emph{Equivalents for stdio variables:}
  71 _stdin_r        _stdout_r       _stderr_r
  72
  73 @page
  74 @exdent @emph{Stdio functions:}
  75 _fdopen_r       _perror_r       _tempnam_r
  76 _fopen_r        _putchar_r      _tmpnam_r
  77 _getchar_r      _puts_r         _tmpfile_r
  78 _gets_r         _remove_r       _vfprintf_r
  79 _iprintf_r      _rename_r       _vsnprintf_r
  80 _mkstemp_r      _snprintf_r     _vsprintf_r
  81 _mktemp_t       _sprintf_r
  82
  83 @exdent @emph{Signal functions:}
  84 _init_signal_r  _signal_r
  85 _kill_r         __sigtramp_r
  86 _raise_r
  87
  88 @exdent @emph{Stdlib functions:}
  89 _calloc_r       _mblen_r        _setenv_r
  90 _dtoa_r         _mbstowcs_r     _srand_r
  91 _free_r         _mbtowc_r       _strtod_r
  92 _getenv_r       _memalign_r     _strtol_r
  93 _mallinfo_r     _mstats_r       _strtoul_r
  94 _malloc_r       _putenv_r       _system_r
  95 _malloc_r       _rand_r         _wcstombs_r
  96 _malloc_stats_r _realloc_r      _wctomb_r
  97
  98 @exdent @emph{String functions:}
  99 _strdup_r       _strtok_r
 100
 101 @exdent @emph{System functions:}
 102 _close_r        _link_r         _unlink_r
 103 _execve_r       _lseek_r        _wait_r
 104 _fcntl_r        _open_r         _write_r
 105 _fork_r         _read_r
 106 _fstat_r        _sbrk_r
 107 _gettimeofday_r _stat_r
 108 _getpid_r       _times_r
 109
 110 @ifset STDIO64
 111 @exdent @emph{Additional 64-bit I/O System functions:}
 112 _fstat64_r      _lseek64_r      _open64_r
 113 @end ifset
 114
 115 @exdent @emph{Time function:}
 116 _asctime_r
 117 @end example