Writing Bug-Free C Code A Programming Style That Automatically Detects Bugs in C Code by Jerry Jongerius / January 1995

Before you can write bug-free code, you must have a bug-free, rock-solid base.

Not all C library functions are rock-solid. A layer that is rock-solid needs to be coded.

Microsoft has recently started the Microsoft Developer Network. It is a program that is intended to get as much information and technical resources as possible into the hands of developers. The program distributes information in the form of a CD and a Windows-based browser. I highly recommend this program to developers. The Microsoft Developer Network can be reached through the Internet at http://msdn.microsoft.com

3.1.1 A MS-DOS Bug An example of a bug that was found in the MS-DOS operating system involves lost clusters. It was detected by an automated testing procedure §7.24. As the automated testing function would run, invariably it would eventually run out of disk space, but the function never created any file large enough to even come close to running out of disk space. As it turned out, disk clusters were being lost by the operating system on a regular basis and eventually the disk would run out of free clusters. The only way to recover the lost clusters was to run the CHKDSK program provided by the operating system. This bug is a confirmed bug in MS-DOS 3.2 and MS-DOS 3.3, the only versions available when the bug was discovered. The bug does not exist in MS-DOS 5.0 and later versions. C program that shows MS-DOS version 3.3 lost cluster bug #include <fcntl.h> #include <sys\types.h> #include <sys\stat.h> #include <io.h> #include <stdio.h> int main(void) { char c; int fh = creat( "it.tmp", S_IREAD|S_IWRITE ); lseek( fh, 81920, SEEK_SET ); write( fh, &c, 1 ); chsize( fh, 81920 ); lseek( fh, 122880, SEEK_SET ); write( fh, &c, 1 ); close( fh ); return 0; } /* main */ Running this program repeatedly under MS-DOS 3.2 or MS-DOS 3.3 will cause the lost cluster bug. Run CHKDSK to recover the lost clusters.

3.1.2 Windows Bugs As any early Windows developer will tell you, Windows was a buggy operating system. Over the course of five years, I accumulated over six three-ring binders full of correspondence with Microsoft support concerning bugs in the Windows system. With the introduction of Windows 3.0, I noticed a significant drop in the number of problems that I was reporting. I attribute this reduction to the fact that Windows 3.0 was a protected-mode operating system (previously it was not). Many types of errors cause a CPU fault and the error can be pinpointed immediately. However, the Windows 3.0 system was still a little shaky when it came to DOS boxes, the emulation of a MS-DOS PC in a Windows window. With the introduction of Windows 3.1, the number of bugs that I report has dropped dramatically. I consider Windows 3.1 to be a stable operating environment. In fact, on my development machine, I stay in Windows all day and use DOS boxes to run my MS-DOS applications. My machine may crash once a week. Not too bad, but still room for improvement. However, there is a particularly nasty bug I have found that still exists in Windows 3.1. Luckily, the likelihood that you will ever encounter the bug is almost nil. The bug is that sometimes the Windows multitasker does not switch to the correct PSP when a Windows application performs disk I/O. What this means is that a file handle that should be correct is not, because the program is in the open file context of another application! A little background may be needed to explain why this can even occur. When Windows multitasks applications, it has to keep a tremendous amount of information around for each application. One piece of that information is the open files context. In order to significantly speed up task switching in Windows, the open files context is not switched until the task actually performs an operation that requires the open files context. Reading and writing a disk file is an example of an operation that would cause a true open files context switch. Since most applications rarely perform disk I/O relative to the amount of CPU time they need, this delayed context switch of the open files context speeds up multitasking. The bug occurs when, in the course of multitasking applications, the Windows kernel incorrectly thinks that it is truly in the open files context of the currently running application, when, in fact, it is in the open files context of another application. Microsoft has been slow to fix this problem since the circumstances that cause the bug to occur are extreme. The only reason I found this bug in the first place is because of an automated testing procedure I used to test the correctness of a new module. This procedure caused almost continuous I/O to occur and every once in a great while, an I/O would fail under low memory conditions. A Windows 3.1 bug. There is another bug that I found that anyone can reproduce easily on any Windows 3.1 machine. First, run the standard Notepad application. Go into the file open dialog and click with the mouse on the OK button. Now press and hold down the space bar. While continuing to hold down the space bar, press the ESC key. This causes a General Protection Fault. The problem has to do with the dialog manager inside the Windows kernel. The fault occurs because both an IDOK and an IDCANCEL are being sent to the dialog callback procedure when in reality, only one message should be sent. This is a problem with all dialogs in all applications. However, the application may or may not fault. It just depends upon how the application was written to respond to the IDOK and IDCANCEL messages. This bug is fixed in Windows 3.11.

Code with an assumption
int fh = open(....);
if (fh!=-1) {
    close(fh);
    }

Provide a code wrapper around all system calls.

Use macros as an aid to porting so that your code base does not change at all.

Porting aids for Microsoft C8 segmented architecture
#define FAR _far
#define NEAR _near
#define FASTCALL _fastcall
#define PASCAL _pascal
#define EXPORT _export
#define BASEDIN(seg) _based(_segname(#seg))


Porting aids for flat model programs
#define FAR
#define NEAR
#define FASTCALL
#define PASCAL
#define EXPORT
#define BASEDIN(seg)

Using a far pointer to a char, not a good idea
char FAR*lpMem;

LPSTR typedef, a better idea
typedef char FAR*LPSTR;

Try to hide how something works to provide an abstraction that aids

EXTERNC macro
/*--- EXTERNC depends upon C/C++ ---*/
#ifdef __cplusplus
#define EXTERNC extern "C"
#else
#define EXTERNC
#endif

Using EXTERNC
EXTERNC type APIENTRY FunctionName( argument-types );

Assertion statements provide run-time checking of design-time assumptions.

Microsoft C8 assert() macro, do not use
#define assert(exp) \
  ( (exp) ? (void) 0 : _assert(#exp, __FILE__, __LINE__) )

There is an additional problem that is specific to the Windows programming environment. In Windows DLLs, it is possible to declare a function that, when called, does not switch to the DLLs data segment, but instead keeps the current caller's data segment. If you were to use an assertion statement in one of these functions, the string pointer to the filename would be incorrect. The solution is to declare the __FILE__ string to be a code segment (CSCHAR §2.1.8) variable. This way, it does not matter what data segment is current.

Use WinAssert() on a block of code to produce code that is fault-tolerant.

WinAssert(), non-fault-tolerant syntax
WinAssert(expression);


WinAssert(), fault-tolerant syntax
WinAssert(expression) {
    (block of code)
    }

WinAssert() implementation
#define USEWINASSERT CSCHAR szSRCFILE[]=__FILE__;   \
  BOOL static NEAR _DoWinAssert( int nLine ) {      \
    ReportWinAssert(szSRCFILE, nLine);              \
    WinAssert(nLine);                               \
    return(FALSE);                                  \
    }
#define AssertError _DoWinAssert(__LINE__)
#define WinAssert(exp) if (!(exp)) {AssertError;} else

ReportWinAssert() function prototype
EXTERNC void APIENTRY ReportWinAssert( LPSTR, int );

Using WinAssert()
#include <app.h>
USEWINASSERT
  .
  .
  .
void LOCAL TestingWinAssert( int nValue )
{
    WinAssert(nValue>0) {
        ...
        }

} /* TestingWinAssert */

WinAssert(), used incorrectly
WinAssert((x/=2)>0);


WinAssert(), used correctly
x /= 2;
WinAssert(x>0);

Macro names should be in uppercase.

Macros beginning with an underscore are to be used only in other macros, not explicitly in source code.

New data types should be in uppercase.

New data types must be declared with a typedef statement, not a macro definition.

Using typedef to create a new data type
typedef char*PSTR;


Using macros to create a new data type, a bad practice
#define PSTR char*


Using the new PSTR data type
PSTR pA, pB;

Variables should be named using Hungarian notation.

Prefix	Data Type
a	array of given type
b	BOOL: true/false value
by	BYTE
c	char
dw	DWORD
h	handle or abstract pointer
l	long
lp	long pointer
n	int
p	pointer
w	WORD

Table 3-1: Hungarian Notation Prefixes

Hungarian notation allows you to know a variable's data type without seeing the data declaration.

An example from the Windows system is the HICON data type and the hIcon variable name. As another example, let's consider a queue entry data type called LPQUEUEENTRY. A variable name for this could be lpQueueEntry.

A data type must have a single and unique variable derivation.

Functions should be named using the module/verb/noun convention.

• A rock-solid layer needs to be built upon all system level interfaces because system level interfaces contain bugs. You cannot assume that they are bug-free. I have been burned too many times to trust system level calls blindly.
• When you do make assumptions in calling system code, it is best to WinAssert() these situations in a code wrapper. When a function does fail and you assumed that it never would, you want to know about it so that you can fix the problem and reevaluate your assumption.
• Macros can be used as an abstraction layer to allow your code to be ported without having to change your source files. Instead, just change the macros contained in your include files and recompile. The macro name in the source file is specifying what to do. The macro body in the include file is specifying how to do it.
• It is a good idea to use WinAssert()'s generously in your code. The WinAssert() provides run-time checking of design-time assumptions and signals a design flaw when it occurs. Use the fault-tolerant form of WinAssert() whenever possible.
• When programming in a large project, it is crucial that a consistent naming convention be used throughout the entire project. This helps prevent misunderstandings that produce buggy code.
• Macro names should be in uppercase. A macro beginning with an underscore character is intended to be used only in other macros, not explicitly in source code.
• New data types should be in uppercase and declared with a typedef statement, not a macro definition.
• Variables should be named using the Hungarian notation. This notation allows you to know the type of a variable without seeing the data declaration.
• Functions should be named using the module/verb/noun convention.