Randfail can be used to introduce "random" failures into debug builds in
order to test the error paths of your code.  This is done by causing certain
Win32 APIs to fail, or by instrumenting your code.

The following Win32 APIs will be instrumented in a debug build:
	CreateDirectory
	CreateDirectoryEx
	CreateEvent
	CreateFile
	CreateFileMapping
	CreateIoCompletionPort
	CreateMutex
	CreateProcess
	CreateSemaphore
	CreateThread
	GetQueuedCompletionStatus
	OpenEvent
	OpenFileMapping
	OpenMutex
	OpenProcess
	OpenSemaphore
	PostQueuedCompletionStatus
	ReadFile
	WriteFile

When an instrumented Win32 API fails, it will return the failure indicated
by the documentation, but will also SetLastError(ERROR_ARENA_TRASHED).


INSTRUMENTING YOUR CODE

In order for your code to use this library, you must include "randfail.h"
AFTER any other include files.  Also, you must link with exstrace.lib
and call InitAsyncTrace().  By default, the failure of Win32 APIs is
enabled.  If you wish to suppress this behavior, define the
preprocessor symbol NOFAIL_WIN32API.

User code may also be instrumented.  To determine if the failure path should
be taken, call fTimeToFail().  For example:

	#include <windows.h>
	#include "randfail.h"

	BOOL bOK;
	if (fTimeToFail()) {
		bOK = FALSE;
	} else {
		bOK = fMyFunction();
	}

	if (!bOK) {
		// Handle the error here
	}

To suppress the failures in user instrumented code, define NOFAIL_RANDOM.

 

ENABLING RANDOM FAILURES DURING EXECUTION

Before executing your program, you must set the frequency in which you
wish failures to occur in the registry.  Create the following key:

	SOFTWARE\Microsoft\MosTrace\CurrentVersion\DebugAsyncTrace
		FailureRate REG_DWORD nn

where nn is the frequency you wish the errors to occur (every nn calls
to an instrumented api.)  To disable the failures, either delete the
key or set it to zero.