Contents|Index|Previous|Next

# Definitions for OS interface

The following discussions describe the complete set of system definitions (primarily subroutines) required.

The examples shown implement the minimal functionality required to allow libc to link, failing 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 GNUPro C library provides a macro definition for errno in the header file, errno.h, serving to support reentrant routines (see “Reentrancy ” for more discussion). The bridge between these two interpretations of errno is straightforward: the C library routines with OS interface calls capture the errno values returned globally, recording 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, as in the following example.

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

The examples in the following documentation include the following 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() {
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() {
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;
}

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;
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 a character 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 writechar 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++) {
writechar(*ptr++);
}
return len;
}