Subversion Repositories or1k

@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       _mkstemp_r       _remove_r

_fopen_r        _mktemp_r        _rename_r

_getchar_r      _perror_r        _tempnam_r

_gets_r         _putchar_r       _tmpnam_r

_iprintf_r      _puts_r          _tmpfile_r

@exdent @emph{Signal functions:}

_raise_r        _signal_r

@exdent @emph{Stdlib functions:}

@c FIXME! dtoa undoc; should _dtoa_r be mentioned?

_dtoa_r         _realloc_r      _strtoul_r

_free_r         _srand_r        _system_r

_malloc_r       _strtod_r

_rand_r         _strtol_r

@exdent @emph{String functions:}

_strtok_r

@exdent @emph{System functions:}

_close_r        _lseek_r        _stat_r

_fork_r         _open_r         _unlink_r

_fstat_r        _read_r         _wait_r

_link_r         _sbrk_r         _write_r

@exdent @emph{Time function:}

_asctime_r

@end example