1 /* This header file provides the reentrancy. */ 2 3 /* The reentrant system calls here serve two purposes: 4 5 1) Provide reentrant versions of the system calls the ANSI C library 6 requires. 7 2) Provide these system calls in a namespace clean way. 8 9 It is intended that *all* system calls that the ANSI C library needs 10 be declared here. It documents them all in one place. All library access 11 to the system is via some form of these functions. 12 13 The target may provide the needed syscalls by any of the following: 14 15 1) Define the reentrant versions of the syscalls directly. 16 (eg: _open_r, _close_r, etc.). Please keep the namespace clean. 17 When you do this, set "syscall_dir" to "syscalls" and add 18 -DREENTRANT_SYSCALLS_PROVIDED to newlib_cflags in configure.host. 19 20 2) Define namespace clean versions of the system calls by prefixing 21 them with '_' (eg: _open, _close, etc.). Technically, there won't be 22 true reentrancy at the syscall level, but the library will be namespace 23 clean. 24 When you do this, set "syscall_dir" to "syscalls" in configure.host. 25 26 3) Define or otherwise provide the regular versions of the syscalls 27 (eg: open, close, etc.). The library won't be reentrant nor namespace 28 clean, but at least it will work. 29 When you do this, add -DMISSING_SYSCALL_NAMES to newlib_cflags in 30 configure.host. 31 32 4) Define or otherwise provide the regular versions of the syscalls, 33 and do not supply functional interfaces for any of the reentrant 34 calls. With this method, the reentrant syscalls are redefined to 35 directly call the regular system call without the reentrancy argument. 36 When you do this, specify both -DREENTRANT_SYSCALLS_PROVIDED and 37 -DMISSING_SYSCALL_NAMES via newlib_cflags in configure.host and do 38 not specify "syscall_dir". 39 40 Stubs of the reentrant versions of the syscalls exist in the libc/reent 41 source directory and are provided if REENTRANT_SYSCALLS_PROVIDED isn't 42 defined. These stubs call the native system calls: _open, _close, etc. 43 if MISSING_SYSCALL_NAMES is *not* defined, otherwise they call the 44 non-underscored versions: open, close, etc. when MISSING_SYSCALL_NAMES 45 *is* defined. 46 47 By default, newlib functions call the reentrant syscalls internally, 48 passing a reentrancy structure as an argument. This reentrancy structure 49 contains data that is thread-specific. For example, the errno value is 50 kept in the reentrancy structure. If multiple threads exist, each will 51 keep a separate errno value which is intuitive since the application flow 52 cannot check for failure reliably otherwise. 53 54 The reentrant syscalls are either provided by the platform, by the 55 libc/reent stubs, or in the case of both MISSING_SYSCALL_NAMES and 56 REENTRANT_SYSCALLS_PROVIDED being defined, the calls are redefined to 57 simply call the regular syscalls with no reentrancy struct argument. 58 59 A single-threaded application does not need to worry about the reentrancy 60 structure. It is used internally. 61 62 A multi-threaded application needs either to manually manage reentrancy 63 structures or use dynamic reentrancy. 64 65 Manually managing reentrancy structures entails calling special reentrant 66 versions of newlib functions that have an additional reentrancy argument. 67 For example, _printf_r. By convention, the first argument is the 68 reentrancy structure. By default, the normal version of the function 69 uses the default reentrancy structure: _REENT. The reentrancy structure 70 is passed internally, eventually to the reentrant syscalls themselves. 71 How the structures are stored and accessed in this model is up to the 72 application. 73 74 Dynamic reentrancy is specified by the __DYNAMIC_REENT__ flag. This 75 flag denotes setting up a macro to replace _REENT with a function call 76 to __getreent(). This function needs to be implemented by the platform 77 and it is meant to return the reentrancy structure for the current 78 thread. When the regular C functions (e.g. printf) go to call internal 79 routines with the default _REENT structure, they end up calling with 80 the reentrancy structure for the thread. Thus, application code does not 81 need to call the _r routines nor worry about reentrancy structures. */ 82 83 /* WARNING: All identifiers here must begin with an underscore. This file is 84 included by stdio.h and others and we therefore must only use identifiers 85 in the namespace allotted to us. */ 86 87 #ifndef _REENT_H_ 88 #ifdef __cplusplus 89 extern "C" { 90 #endif 91 #define _REENT_H_ 92 93 #include <sys/reent.h> 94 #include <sys/_types.h> 95 96 #define __need_size_t 97 #define __need_ptrdiff_t 98 #include <stddef.h> 99 100 /* FIXME: not namespace clean */ 101 struct stat; 102 struct tms; 103 struct timeval; 104 struct timezone; 105 struct _reent; 106 107 #ifdef __cplusplus 108 } 109 #endif 110 #endif /* _REENT_H_ */ 111