CLW

Section: C Library Wrapper (n)
Updated: 2002-11-19
Index

NAME

CLW

DESCRIPTION

The C Library Wrapper is a tool for finding errors in C programs. It does so by encapsulating all dangerous libc functions and by providing a safer alternative and memory checking mechanism.

TYPICAL USE

CLW can be used in three different ways. The programmer can replace every standard c-library function by a CLW alternative. CLW has replacements for every C library function of the ANSI C (90) standard. Example:


int main ( void )
{
        FILE* infile = clw_fopen("infile.txt", "r" );
        char buff[80];
        clw_fgets(buff, 80, infile );
}

The example shows that two function have been replaced by CLW wrappers. CLW adds checking to both functions and will issue a warning when one of the two functions fails to operate correctly. For example, when the file "infile.txt" would not exist, the output would be:


ERROR: Exception 65536 : fopen : No such file or directory
Problem occured at:
Function main() at line 5 of "test.c" 
ERROR: Exception 64 : fgets : illegal stream
Problem occured at:
Function main() at line 7 of "test.c"

If the programmer would not use the wrapper functions bu the standard C library functions instead, the result of this would be undefined (probable a segv or bus error). In order to use clw this way, the programmer must include clw.h and must link the clw library (libclw.a) to the program. Also, the program musr be invoked by the clw_run script:


$ gcc -g -I/usr/local/clw/include test.c -lclw
$ clw_run ./a.out

WRAPPER MODE

It is also possible to use CLW without changing any of the code (i.e. by using the standard C library functions instead of the wrapper functions). The code would then be:


int main ( void )
{
        FILE* infile = fopen("infile.txt", "r" );
        char buff[80];
        fgets(buff, 80, infile );
}

The code is then compiles using clw_cc and executed with clw_run:


$ clw_cc -g test.c 
$ clw_run ./a.out

The code will be automatically instrumented by clw such that the standard C library functions will automatically be replaced by the wrappers.

NON-INTRUSIVE MODE

It is also possible to use CLW without recompiling the code. In this case, only memory checking will be in effect when using clw_run.

A stack trace is generated for memory leaks when the code was compiled with debug information included (i.e. -g option for gcc).


$ cat test.c
int main ( void )
{
                char* help = strdup("help");
                printf("%s, help );
                sprintf(help, "%s", "me" );
                printf("%s, help );
                return 0;
}
$ gcc -g test.c
$ ./a.out
help
me

$ clw_run ./a.out
help
me
ERROR: malloc list not empty (1 blocks) ((nil))
Problem occured from thread 1, pid 5819 at:
------------------- malloc dump -------------------
addres at 0x080495c4 allocated size: 5 bytes  "me"
allocated from thread 1, pid 5819 at:
Function main() at line 4 of "test.c"

POSIX THREADS

The CLW does support POSIX threads (pthreads). When your program uses the pthread library, you add -pthread to the invokation of the clw_cc and clw_run scripts. The output will contain real values for the thread id's. Example:


$ cat test.c
void f( void )
{
        char* hello = strdup("hello");
        printf("%s, hello );
}

int main ( void )
{
                pthread_t p;
                char* world = strdup("world");
                pthread_create( &p, NULL, f, NULL );
                printf("%s, world );
                pthread_join(p, NULL);
                return 0;
}

$ gcc -g test.c -lpthread
$ clw_run -pthread ./a.out 
hello
world
ERROR: malloc list not empty (3 blocks) ((nil))
Problem occured from thread 8192, pid 5869 at:
------------------- malloc dump -------------------
addres at 0x080496b4 allocated size: 6 bytes  "world"
allocated from thread 8192, pid 5869 at:
Function main() at line 12 of "test.c" 
addres at 0x08049724 allocated size: 8160 bytes  
allocated from thread 8192, pid 5869 at:
Function main() at line 13 of "test.c" 
addres at 0x0804b770 allocated size: 6 bytes  "hello"
allocated from thread 8194, pid 5871 at:
Function f() at line 5 of "test.c" 
---------------------------------------------------

Copyright


Erwin Nijmeijer (GPL)