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