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 |
---|