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