Next: Reentrant Syscalls, Up: Syscalls [Contents][Index]

### 12.1 Definitions for OS interface

This is the complete set of system definitions (primarily subroutines) required; the examples shown implement the minimal functionality required to allow `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 `errno`. However, the Red Hat newlib C library provides a macro definition for `errno` in the header file `errno.h`, as part of its support for reentrant routines (see Reentrancy).

The bridge between these two interpretations of `errno` is straightforward: the C library routines with OS interface calls capture the `errno` values returned globally, and record them in the appropriate field of the reentrancy structure (so that you can query them using the `errno` macro from `errno.h`).

This mechanism becomes visible when you write stub routines for OS interfaces. You must include `errno.h`, then disable the macro, like this:

    #include <errno.h>
    #undef errno
    extern int errno;

The examples in this chapter include this treatment of `errno`.

`_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 (`exit`, `system`).

`close`

  Close a file. Minimal implementation:

      int close(int file) {
        return -1;
      }

`environ`

  A pointer to a list of environment variables and their values. For a minimal environment, this empty list is adequate:

      char *__env[1] = { 0 };
      char **environ = __env;

`execve`

  Transfer control to a new process. Minimal implementation (for a system without processes):

      #include <errno.h>
      #undef errno
      extern int errno;
      int execve(char *name, char **argv, char **env) {
        errno = ENOMEM;
        return -1;
      }

`fork`

  Create a new process. Minimal implementation (for a system without processes):

      #include <errno.h>
      #undef errno
      extern int errno;
      int fork(void) {
        errno = EAGAIN;
        return -1;
      }

`fstat`

  Status of an open file. For consistency with other minimal implementations in these examples, all files are regarded as character special devices. The `sys/stat.h` header file required is distributed in the `include` subdirectory for this C library.

      #include <sys/stat.h>
      int fstat(int file, struct stat *st) {
        st->st_mode = S_IFCHR;
        return 0;
      }

`getpid`

  Process-ID; this is sometimes used to generate strings unlikely to conflict with other processes. Minimal implementation, for a system without processes:

      int getpid(void) {
        return 1;
      }

`isatty`

  Query whether output stream is a terminal. For consistency with the other minimal implementations, which only support output to `stdout`, this minimal implementation is suggested:

      int isatty(int file) {
        return 1;
      }

`kill`

  Send a signal. Minimal implementation:

      #include <errno.h>
      #undef errno
      extern int errno;
      int kill(int pid, int sig) {
        errno = EINVAL;
        return -1;
      }

`link`

  Establish a new name for an existing file. Minimal implementation:

      #include <errno.h>
      #undef errno
      extern int errno;
      int link(char *old, char *new) {
        errno = EMLINK;
        return -1;
      }

`lseek`

  Set position in a file. Minimal implementation:

      int lseek(int file, int ptr, int dir) {
        return 0;
      }

`open`

  Open a file. Minimal implementation:

      int open(const char *name, int flags, int mode) {
        return -1;
      }

`read`

  Read from a file. Minimal implementation:

      int read(int file, char *ptr, int len) {
        return 0;
      }

`sbrk`

  Increase program data space. As `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 `_end` automatically defined by the GNU linker.

      caddr_t sbrk(int incr) {
        extern char _end;		/* 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;
      }

`stat`

  Status of a file (by name). Minimal implementation:

      int stat(char *file, struct stat *st) {
        st->st_mode = S_IFCHR;
        return 0;
      }

`times`

  Timing information for current process. Minimal implementation:

      int times(struct tms *buf) {
        return -1;
      }

`unlink`

  Remove a file’s directory entry. Minimal implementation:

      #include <errno.h>
      #undef errno
      extern int errno;
      int unlink(char *name) {
        errno = ENOENT;
        return -1;
      }

`wait`

  Wait for a child process. Minimal implementation:

      #include <errno.h>
      #undef errno
      extern int errno;
      int wait(int *status) {
        errno = ECHILD;
        return -1;
      }

`write`

  Write to a file. `libc` subroutines will use this system routine for output to all files, including `stdout`—so if you need to generate any output, for example to a serial port for debugging, you should make your minimal `write` capable of doing this. The following minimal implementation is an incomplete example; it relies on a `outbyte` subroutine (not shown; typically, you must write this in assembler from examples provided by your hardware manufacturer) to actually perform the output.

      int write(int file, char *ptr, int len) {
        int todo;

        for (todo = 0; todo < len; todo++) {
          outbyte (*ptr++);
        }
        return len;
      }

Next: Reentrant Syscalls, Up: Syscalls [Contents][Index]