Subversion Repositories openrisc_me

@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