JC's C Debug Package

JC's C Debug Package

This is John Chambers' C debug package. See V.html or V.d for details. This is a collection of tools that are useful in finding out what's going wrong in C programs. It is especially useful in portability testing, since its tests won't compile or run correctly unless you have gotten the configuration stuff right.

I've written a lot of this code myself. I've also borrowed pieces from other people's collections. I've done a fair amount of work making the pieces work together, so you might not recognize something of yours that I've borrowed.

Everything here is freely available under the terms of the GPL (Gnu Public License). You may use it in any C software. If you make any significant changes or improvements, let me know and I'll try to incorporate your changes into my version. This software is designed to be easily added and removed from C programs, so there shouldn't be any legal problems with incorporating it into a product. And once you are confident that it's working correctly, you might want to remove the debug stuff anyway, because it does make your program bigger and (slightly) slower.

The sh subdirectory has an Unshar script that may be useful if you received this in shar format and don't have unshar. It strips away email headers and feeds the rest of each file to sh for unpacking.

You will have to create a local.h file before things will compile. One way to do this is by running the Configure script that is included. But this will probably only work well if you are running on a machine similar to one that Configure has been tested on. You will want to look at the local.h file that it generates and do a bit of editing.

If you just unpacked this package on your machine, chances are that any local.h file here is not correct. If you are on one of the systems for which a foo_local.h file is included, you can probably use it as a prototype. Also, it is easier to get things to compile first if you use the hostype script to set up your environment. For csh users, the command is:

	eval `hostype -cshe`
Alternatively, run "hostype -cshe" and add its output to your .login file. If you are using a different shell, look at hostype to see what option you should use.

After you have a local.h file, type:

	make all
and it should all compile. This will also build a Vtest program that is for testing the package itself. Depending on debug level, Vtest generates all sorts of output, some of it pretty strange-looking at first. You will have to examine the program to see whether the output is correct. This is intentional; in examining Vtest, you will see how pieces of this debug package are used. You should read V.d before running Vtest.

The "make" command without args will build only libV.a, which is what you need (along with V.h and local.h) to use this package.

You might have noticed all those *.b files in this directory and wondered what they're all about. They are "prototype" *.c files with a lot of optional debug stuff included, in the form of lines with ':' in column 1.

This is a simple trick that allows us to strip out the debug stuff with a single-line change in the Makefile. We feed these files to the b-c script, which is actually just a call of sed that either enables a ':' line or blanks it out, depending on the character in column 2. It's simple to build everything with all the debugging enabled, and then recompile with the higher-level debug stuff deleted once you trust that it is reliable.


It's a good idea to run the test programs that are included here. If you do, they'll tell you a lot about things that will break other programs, and fixing them here probably means fixing them in any programs that use the V package

You must have perl (4 or 5) to run the automated tests. Type:

	make test
This will use the Test program, which will in turn run all the programs in the test/prog directory, and report on their success or failure. The Test script is a tool that you might want to examing; it is quite useful in building automated (regression) tests for other programs.

If you don't have perl (and for some silly reason can't get it), you can run the test scripts yourself. Their output should be compared with the source code, to see if it is correct. Samples of correct output are in test/stdout/* and test/stderr/*. Since some of the details of the tests' output will vary from system to system, you should examine the output to see if the minor differences are relevant.

Note that several of the tests do things that intentionally produce failures; they will warn you of the errors, and you can check to see that the correct errors actually occur.

Recommended test commands if you don't have perl:

		Vtest %d4
		setenv D_Vtest 4Vtest.out; Vtest
		memtest %d2

errno handling

One of the real pains in Unix is the crappy support for errno. This debug packages builds a pair of files, err.h and err.b, that provide a more useful interface to errno than the usual sys_errlist[]. However, getting it built correctly is a portability hassle. The errnotbl perl script does the job by reading from the system's table of error codes, mnemonics and messages.

Unfortuntaely, this table is kept in several different places and formats by various vendors. On some, the "man 2 intro" command gets it; on others, you need "man 2 errno"; on yet others, neither of these works, but /usr/include/sys/errno.h contains the messages in comments. We can handle any of these three. But you may need to edit the errnotbl script and tell it which of the three $pat patterns to use. You may also need to edit the Makefile, and modify the call of errnotbl to do the right thing. Alternatively, you may have received a version that has some *_err.h and *_err.b files for a similar system to yours. You can use these, though the result may not be quite right for your system. Sorry that it can't be done any better than this. If you find a way to improve it, let me know.