diff options
Diffstat (limited to 'newlib/libc/sys.tex')
| -rw-r--r-- | newlib/libc/sys.tex | 437 |
1 files changed, 0 insertions, 437 deletions
diff --git a/newlib/libc/sys.tex b/newlib/libc/sys.tex deleted file mode 100644 index 3182b71c5..000000000 --- a/newlib/libc/sys.tex +++ /dev/null @@ -1,437 +0,0 @@ -@c -*- Texinfo -*- -@node Syscalls -@chapter System Calls - -@cindex linking the C library -The C subroutine library depends on a handful of subroutine calls for -operating system services. If you use the C library on a system that -complies with the POSIX.1 standard (also known as IEEE 1003.1), most of -these subroutines are supplied with your operating system. - -If some of these subroutines are not provided with your system---in -the extreme case, if you are developing software for a ``bare board'' -system, without an OS---you will at least need to provide do-nothing -stubs (or subroutines with minimal functionality) to allow your -programs to link with the subroutines in @code{libc.a}. - -@menu -* Stubs:: Definitions for OS interface -* Reentrant Syscalls:: Reentrant covers for OS subroutines -@end menu - -@node Stubs -@section Definitions for OS interface -@cindex stubs - -@cindex subroutines for OS interface -@cindex OS interface subroutines -This is the complete set of system definitions (primarily subroutines) -required; the examples shown implement the minimal functionality -required to allow @code{libc} to link, and fail gracefully where OS -services are not available. - -Graceful failure is permitted by returning an error code. A minor -complication arises here: the C library must be compatible with -development environments that supply fully functional versions of these -subroutines. Such environments usually return error codes in a global -@code{errno}. However, the Cygnus C library provides a @emph{macro} -definition for @code{errno} in the header file @file{errno.h}, as part -of its support for reentrant routines (@pxref{Reentrancy,,Reentrancy}). - -@cindex @code{errno} global vs macro -The bridge between these two interpretations of @code{errno} is -straightforward: the C library routines with OS interface calls -capture the @code{errno} values returned globally, and record them in -the appropriate field of the reentrancy structure (so that you can query -them using the @code{errno} macro from @file{errno.h}). - -This mechanism becomes visible when you write stub routines for OS -interfaces. You must include @file{errno.h}, then disable the macro, -like this: - -@example -#include <errno.h> -#undef errno -extern int errno; -@end example - -@noindent -The examples in this chapter include this treatment of @code{errno}. - -@ftable @code -@item _exit -Exit a program without cleaning up files. If your system doesn't -provide this, it is best to avoid linking with subroutines that require -it (@code{exit}, @code{system}). - -@item close -Close a file. Minimal implementation: - -@example -int close(int file)@{ - return -1; -@} -@end example - -@item environ -A pointer to a list of environment variables and their values. For a -minimal environment, this empty list is adequate: - -@example -char *__env[1] = @{ 0 @}; -char **environ = __env; -@end example - -@item execve -Transfer control to a new process. Minimal implementation (for a system -without processes): - -@example -#include <errno.h> -#undef errno -extern int errno; -int execve(char *name, char **argv, char **env)@{ - errno=ENOMEM; - return -1; -@} -@end example - -@item fork -Create a new process. Minimal implementation (for a system without processes): - -@example -#include <errno.h> -#undef errno -extern int errno; -int fork() @{ - errno=EAGAIN; - return -1; -@} -@end example - -@item fstat -Status of an open file. For consistency with other minimal -implementations in these examples, all files are regarded as character -special devices. The @file{sys/stat.h} header file required is -distributed in the @file{include} subdirectory for this C library. - -@example -#include <sys/stat.h> -int fstat(int file, struct stat *st) @{ - st->st_mode = S_IFCHR; - return 0; -@} -@end example - -@item getpid -Process-ID; this is sometimes used to generate strings unlikely to -conflict with other processes. Minimal implementation, for a system -without processes: - -@example -int getpid() @{ - return 1; -@} -@end example - -@item isatty -Query whether output stream is a terminal. For consistency with the -other minimal implementations, which only support output to -@code{stdout}, this minimal implementation is suggested: - -@example -int isatty(int file)@{ - return 1; -@} -@end example - -@item kill -Send a signal. Minimal implementation: - -@example -#include <errno.h> -#undef errno -extern int errno; -int kill(int pid, int sig)@{ - errno=EINVAL; - return(-1); -@} -@end example - -@item link -Establish a new name for an existing file. Minimal implementation: - -@example -#include <errno.h> -#undef errno -extern int errno; -int link(char *old, char *new)@{ - errno=EMLINK; - return -1; -@} -@end example - -@item lseek -Set position in a file. Minimal implementation: - -@example -int lseek(int file, int ptr, int dir)@{ - return 0; -@} -@end example - -@c FIXME! Why no stub for open? - -@item read -Read from a file. Minimal implementation: - -@example -int read(int file, char *ptr, int len)@{ - return 0; -@} -@end example - -@item sbrk -Increase program data space. As @code{malloc} and related functions -depend on this, it is useful to have a working implementation. The -following suffices for a standalone system; it exploits the symbol -@code{end} automatically defined by the GNU linker. - -@example -@group -caddr_t sbrk(int incr)@{ - extern char end; /* @r{Defined by the linker} */ - static char *heap_end; - char *prev_heap_end; - - if (heap_end == 0) @{ - heap_end = &end; - @} - prev_heap_end = heap_end; - if (heap_end + incr > stack_ptr) - @{ - _write (1, "Heap and stack collision\n", 25); - abort (); - @} - - heap_end += incr; - return (caddr_t) prev_heap_end; -@} -@end group -@end example - -@item stat -Status of a file (by name). Minimal implementation: - -@example -int stat(char *file, struct stat *st) @{ - st->st_mode = S_IFCHR; - return 0; -@} -@end example - -@item times -Timing information for current process. Minimal implementation: - -@example -int times(struct tms *buf)@{ - return -1; -@} -@end example - -@item unlink -Remove a file's directory entry. Minimal implementation: - -@example -#include <errno.h> -#undef errno -extern int errno; -int unlink(char *name)@{ - errno=ENOENT; - return -1; -@} -@end example - -@item wait -Wait for a child process. Minimal implementation: -@example -#include <errno.h> -#undef errno -extern int errno; -int wait(int *status) @{ - errno=ECHILD; - return -1; -@} -@end example - -@item write -Write a character to a file. @file{libc} subroutines will use this -system routine for output to all files, @emph{including} -@code{stdout}---so if you need to generate any output, for example to a -serial port for debugging, you should make your minimal @code{write} -capable of doing this. The following minimal implementation is an -incomplete example; it relies on a @code{writechar} subroutine (not -shown; typically, you must write this in assembler from examples -provided by your hardware manufacturer) to actually perform the output. - -@example -@group -int write(int file, char *ptr, int len)@{ - int todo; - - for (todo = 0; todo < len; todo++) @{ - writechar(*ptr++); - @} - return len; -@} -@end group -@end example - -@end ftable - -@page -@node Reentrant Syscalls -@section Reentrant covers for OS subroutines - -Since the system subroutines are used by other library routines that -require reentrancy, @file{libc.a} provides cover routines (for example, -the reentrant version of @code{fork} is @code{_fork_r}). These cover -routines are consistent with the other reentrant subroutines in this -library, and achieve reentrancy by using a reserved global data block -(@pxref{Reentrancy,,Reentrancy}). - -@c FIXME!!! The following ignored text specifies how this section ought -@c to work; however, both standalone info and Emacs info mode fail when -@c confronted with nodes beginning `_' as of 24may93. Restore when Info -@c readers fixed! -@ignore -@menu -* _open_r:: Reentrant version of open -* _close_r:: Reentrant version of close -* _lseek_r:: Reentrant version of lseek -* _read_r:: Reentrant version of read -* _write_r:: Reentrant version of write -* _link_r:: Reentrant version of link -* _unlink_r:: Reentrant version of unlink -* _stat_r:: Reentrant version of stat -* _fstat_r:: Reentrant version of fstat -* _sbrk_r:: Reentrant version of sbrk -* _fork_r:: Reentrant version of fork -* _wait_r:: Reentrant version of wait -@end menu - -@down -@include reent/filer.def -@include reent/execr.def -@include reent/statr.def -@include reent/fstatr.def -@include reent/linkr.def -@include reent/unlinkr.def -@include reent/sbrkr.def -@up -@end ignore - -@ftable @code -@item _open_r -A reentrant version of @code{open}. It takes a pointer -to the global data block, which holds @code{errno}. - -@example -int _open_r(void *@var{reent}, - const char *@var{file}, int @var{flags}, int @var{mode}); -@end example - -@item _close_r -A reentrant version of @code{close}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _close_r(void *@var{reent}, int @var{fd}); -@end example - -@item _lseek_r -A reentrant version of @code{lseek}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -off_t _lseek_r(void *@var{reent}, - int @var{fd}, off_t @var{pos}, int @var{whence}); -@end example - -@item _read_r -A reentrant version of @code{read}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -long _read_r(void *@var{reent}, - int @var{fd}, void *@var{buf}, size_t @var{cnt}); -@end example - -@item _write_r -A reentrant version of @code{write}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -long _write_r(void *@var{reent}, - int @var{fd}, const void *@var{buf}, size_t @var{cnt}); -@end example - -@item _fork_r -A reentrant version of @code{fork}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _fork_r(void *@var{reent}); -@end example - -@item _wait_r -A reentrant version of @code{wait}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _wait_r(void *@var{reent}, int *@var{status}); -@end example - -@item _stat_r -A reentrant version of @code{stat}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _stat_r(void *@var{reent}, - const char *@var{file}, struct stat *@var{pstat}); -@end example - -@item _fstat_r -A reentrant version of @code{fstat}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _fstat_r(void *@var{reent}, - int @var{fd}, struct stat *@var{pstat}); -@end example - -@item _link_r -A reentrant version of @code{link}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _link_r(void *@var{reent}, - const char *@var{old}, const char *@var{new}); -@end example - -@item _unlink_r -A reentrant version of @code{unlink}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -int _unlink_r(void *@var{reent}, const char *@var{file}); -@end example - -@item _sbrk_r -A reentrant version of @code{sbrk}. It takes a pointer to the global -data block, which holds @code{errno}. - -@example -char *_sbrk_r(void *@var{reent}, size_t @var{incr}); -@end example -@end ftable |