Win-Fix-Bug Programming Interface V1.03


Quick Reference

BOOL FixBugInit (void);

BOOL FixBugRun (LPTSTR lpCommandLine, LPCTSTR lpCurrentDirectory, DWORD dwFlags);

DWORD BreakPointSet (BPHANDLER bpHandler, LPCTSTR lpExeName, LPCTSTR lpDllName, LPCSTR lpProcName, DWORD dwOffset, DWORD dwExpectedByte, PVOID pvUser);

BOOL BreakPointClear (DWORD dwBreakpointId);

BOOL BreakPointEnable (DWORD dwBreakpointId);

BOOL BreakPointDisable (DWORD dwBreakpointId);

BOOL SingleStep (BPHANDLER bpHandler, PVOID pvUser);

BOOL PatchBytes (LPCTSTR lpExeName, LPCTSTR lpDllName, LPCSTR lpProcName, DWORD dwOffset, const LPBYTE lpbNew, DWORD dwLen, const LPBYTE lpbExpected);

DWORD GetModuleBase (LPCTSTR lpExeName, LPCTSTR lpDllName);

BOOL ReadFunctionArgs (HANDLE hProcess, DWORD dwAddress, LPCSTR lpFormat, ...);

DWORD ReadStringA (HANDLE hProcess, DWORD dwAddress, LPSTR lpStr, LPDWORD pcchStr);

DWORD ReadStringW (HANDLE hProcess, DWORD dwAddress, LPWSTR lpStr, LPDWORD pcchStr);

DWORD FBGetLastError (void);

LPCSTR FBErrorStr (DWORD dwCode);

typedef DWORD (*BPHANDLER) (HANDLE hProcess, CONTEXT *pContext, PVOID pvUser);


API Reference


BOOL FixBugInit (void);

The FixBugInit function initializes the Win-Fix-Bug library.

Parameters

This function has no parameters.

Return Value

If the library has initialized itself successfully, the return value is TRUE.
If the function fails, the return value is FALSE.

Remarks

This function must be called before using any of the other functions in the Win-Fix-Bug package.


BOOL FixBugRun (LPTSTR lpCommandLine, LPCTSTR lpCurrentDirectory, DWORD dwFlags);

The FixBugRun function creates a child process under the Win-Fix-Bug system. It does not return until the child process has exited.

Parameters

lpCommandLine
Pointer to a null-terminated string that specifies the command line to execute.

lpCurrentDirectory
Points to a null-terminated string that specifies the current drive and directory for the child process. The string must be a full path and filename that includes a drive letter. If this parameter is NULL, the new process is created with the same current drive and directory as the calling process.

dwFlags
Additional flags which control the operation of FixBugRun. The following flags can be specified in any combination, except as noted:

Value Meaning

FBR_DEBUG_SUBPROCESSES
If this flag is set, subprocesses of the child process are run under the control of Win-Fix-Bug. If this flag is not specified, break points and patches may only be set in the child process' address space.

FBR_REUSE_CONSOLE
If this flag is set a new console is not created for the application.

Return Value

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Win-Fix-Bug only supports Win32 programs. If lpCommandLine specifies a DOS or 16-bit Windows program the function will fail and the extended error information will be set to ERROR_INVALID_PARAMETER.

See Also

BreakPointSet, BPHANDLER, PatchBytes


DWORD BreakPointSet (BPHANDLER bpHandler, LPCTSTR lpExeName, LPCTSTR lpDllName, LPCSTR lpProcName, DWORD dwOffset, DWORD dwExpectedByte, PVOID pvUser);

The BreakPointSet function sets a break point whose address is specified by exe, module, function name, and offset. When the break point is reached, the process thread is suspended and control is transferred to the user-defined break point handler.

Parameters

bpHandler
Points to the user-defined function which gets called when the break point is encountered. For more information see BPHANDLER.

lpExeName
Points to a null-terminated string that specifies the name of the executable file that the break point applies to. This parameter may be NULL if called within a break point handler to specify the current process.

lpDllName
Points to a null-terminated string that specifies the name of the dynamic-link library (DLL) that the break point applies to. This parameter may be NULL to specify that the break point applies to the executable module.

lpProcName
Points to a null-terminated string containing the function name for the break point, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. The function must exported from the executable or dynamic-link library.

If this parameter is NULL, the base address of the executable image is used.

If the first character of the string is null (ie, lpProcName points to a null string "") then the address used is the absolute address given by dwOffset, otherwise the break point address is given by the function address plus the offset specified in the dwOffset parameter.

dwOffset
Specifies an offset relative to the address determined by the lpProcName parameter for the break point.

dwExpectedByte
The byte at the break point location. If the actual byte found by Win-Fix-Bug differs from this, the break point will not be activated.

If EB_ANY is specified, no check is made.

This parameter may be useful when specifying an address relative to the base of the executable as an additional safety check that the correct address is being used.

pvUser
The value given for this parameter is passed as the pvUser parameter to the handler when the break point is reached.

Return Value

If the function succeeds, the return value is a non-zero break point identifier. Break points are initially enabled when they are set. The identifier can passed to the other break point functions to enable, disable, or clear it.

If the function fails, it returns 0.

Remarks

Keep in mind that a typical scenario involves calling BreakPointSet before running the program with FixBugRun. In this case, the program to be debugged will not be loaded into memory, so it is impossible to determine whether the break point can be successfully applied. The return of a break point identifier only indicates that Win-Fix-Bug was able to internally process the break point.

See Also

FixBugRun, BPHANDLER, BreakPointClear, BreakPointEnable, BreakPointDisable


BOOL BreakPointClear (DWORD dwBreakpointId);

The BreakPointClear function permanently deletes a break point.

Parameters

dwBreakpointId
Specifies the identifier of the break point to be cleared. It must be a valid id returned by BreakPointSet.

Return Value

If the function succeeds, the return value is TRUE.
If an invalid break point identifier is specified, the function returns FALSE.

Remarks

Once a break point has been cleared it may no longer be referred to.

Break points can also be cleared upon exit from their handler by returning the value BPH_CLEAR.

See Also

BreakPointSet, BreakPointEnable, BreakPointDisable


BOOL BreakPointEnable (DWORD dwBreakpointId);

The BreakPointEnable function reactivates break points that were disabled.

Parameters

dwBreakpointId
Specifies the identifier of the break point to be enabled. It must be a valid id returned by BreakPointSet.

Return Value

If the function succeeds, the return value is TRUE.
If an invalid break point identifier is specified, the function returns FALSE.

Remarks

See Also

BreakPointSet, BreakPointClear, BreakPointDisable


BOOL BreakPointDisable (DWORD dwBreakpointId);

The BreakPointDisable function is used to temporarily deactivate break points.

Parameters

dwBreakpointId
Specifies the identifier of the break point to be disabled. It must be a valid id returned by BreakPointSet.

Return Value

If the function succeeds, the return value is TRUE.
If an invalid break point identifier is specified, the function returns FALSE.

Remarks

Disabled break points may be reactivated with the BreakPointEnable function.

Break points can also be disabled upon exit from their handler by returning the value BPH_DISABLE.

See Also

BreakPointSet, BreakPointClear, BreakPointEnable


BOOL SingleStep (BPHANDLER bpHandler, PVOID pvUser);

The SingleStep function begins single stepping a process thread. It may only be called from within a break point handler.

Parameters

bpHandler
Points to the user-defined function which gets called before each instruction being single stepped. The only values which may be returned by the handler are BPH_CLEAR and BPH_REENABLE. For more information see BPHANDLER.

pvUser
The value given for this parameter is passed as the pvUser parameter to the handler when the break point is reached.

Return Value

If the process thread is able to be set up for single stepping, the function returns TRUE.
If the function fails it returns FALSE.

Remarks

This function can only be called from within a break point handler. Single stepping begins after executing the instruction that the break point occurred at. The function specified in bpHandler will be called prior to each instruction in the process thread. To disable single stepping, the handler must return BPH_CLEAR otherwise if BPH_REENABLE is returned single stepping continues.

See Also

BPHANDLER, BreakPointSet


BOOL PatchBytes (LPCTSTR lpExeName, LPCTSTR lpDllName, LPCSTR lpProcName, DWORD dwOffset, const LPBYTE lpbNew, DWORD dwLen, const LPBYTE lpbExpected);

The PatchBytes function replaces bytes of an executable in memory.

Parameters

lpExeName
Points to a null-terminated string that specifies the name of the executable file that the patch applies to. This parameter may be NULL if called within a break point handler to specify the current process.

lpDllName
Points to a null-terminated string that specifies the name of the dynamic-link library (DLL) that the patch applies to. This parameter may be NULL to specify that the patch applies to the executable module.

lpProcName
Points to a null-terminated string containing the function name for the patch, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. The function must exported from the executable or dynamic-link library.

If this parameter is NULL, the base address of the executable image is used.

If the first character of the string is null (ie, lpProcName points to a null string "") then the address used is the absolute address given by dwOffset, otherwise the patch address is given by the function address plus the offset specified in the dwOffset parameter.

dwOffset
Specifies an offset relative to the address determined by the lpProcName parameter for the patch.

lpbNew
Points to a buffer containing the bytes to be patched into the program.

uiLen
Specifies the number of bytes to be patched.

lpbExpected
Points to a buffer containing the bytes which must be present at the patch location. If the bytes found at the patch location do not match these, the patch is not made. This is parameter is provided as a safety check. This parameter may be NULL in which case no check is made.

Return Value

If the function succeeds, the return value TRUE.

If the function fails, it returns FALSE.

Remarks

Keep in mind that a typical scenario involves calling PatchBytes before running the program with FixBugRun. In this case, the program to be patched will not be loaded into memory, so it is impossible to determine whether the patch can be successfully applied. A return value of TRUE only indicates that Win-Fix-Bug was able to add the patch to its internal list.

See Also

FixBugRun


DWORD GetModuleBase (LPCTSTR lpExeName, LPCTSTR lpDllName);

The GetModuleBase function returns the base address for a module which has been loaded into memory by a process running under Win-Fix-Bug.

Parameters

lpExeName
Points to a null-terminated string that specifies the name of the executable file of the process. This parameter may be NULL if called within a break point handler to specify the current process.

lpDllName
Points to a null-terminated string that specifies the name of the dynamic-link library (DLL) to get the load address of. This parameter may be NULL to get the load address of the exe file.

Return Value

If the module specified is currently in memory then the load address is returned.
If the function fails due to the module not being loaded or otherwise, 0 is returned.

Remarks

This function is provided so that data which is global to a module can be addressed. Global module data is always located at a specific offset from the load address.

See Also


BOOL ReadFunctionArgs (HANDLE hProcess, DWORD dwAddress, LPCSTR lpFormat, ...);

The ReadFunctionArgs function reads data from the processes memory and stores it to the location given by the pointers following lpFormat string. Its operation is analogous the scanf() C function.

Parameters

hProcess
Identifies an open handle of the process to read from.

dwAddress
Specifies the address of the first argument to be read. Argument ordering is assumed to be consistent with the C language, ie arguments were pushed onto the stack from left to right.

lpFormat
Specifies a list of argument types. The following characters are used:

specifiercorresponding C data type
ccharacter
sshort integer
iinteger / 32 bit pointer
l__int64
ffloat
ddouble

...
A variable number of pointers to variables which will be used to store the data specified by the lpFormat string follows.

Return Value

If the function succeeds by reading all arguments specified by the format string, it returns TRUE.
If the function fails FALSE is returned.

Remarks

See Also

ReadString


DWORD ReadStringA (HANDLE hProcess, DWORD dwAddress, LPSTR lpStr, LPDWORD pcchStr);
DWORD ReadStringW (HANDLE hProcess, DWORD dwAddress, LPWSTR lpStr, LPDWORD pcchStr);

The ReadStringX function reads a nul terminated ascii or unicode string from another processes memory.

Parameters

hProcess
Identifies an open handle of the process to read from.

dwAddress
Specifies the starting address of the string.

lpStr
Points to a buffer in which to store the string. This parameter may be NULL, in which case the variable pointed to by pcchStr will contain the length of the buffer needed in characters upon return.

pcchStr
Points to a variable which contains the length of the buffer pointed to by lpStr in characters, or 0 if lpStr is NULL. This variable gets the actual number of characters, including the terminating nul upon return. If this parameter is NULL the function fails.

Return Value

If the function succeeds by successful reading a text string it returns TRUE.
If the function fails FALSE is returned.
If the size of the buffer pointed to by lpStr is too small, FBGetLastError will return FB_ERROR_BUFSIZE.

Remarks

See Also

ReadFunctionArgs


DWORD FBGetLastError (void);

The FBGetLastError function returns the code of the most recent error encountered.

Parameters

This function has no parameters.

Return Value

The last error that occurred or 0 (FB_ERROR_SUCCESS) if the last operation was successful.

Remarks

See Also

FBErrorStr


LPCSTR FBErrorStr (DWORD dwCode);

The FBErrorStr function returns a null-terminated string with the text representation of an error code.

Parameters

dwCode
The error code to get.

Return Value

The string representation of the error code is returned.

Remarks

See Also

FBGetLastError


typedef DWORD (*BPHANDLER) (HANDLE hProcess, CONTEXT *pContext, PVOID pvUser);

A BPHANDLER function is a user-defined break point handler. The break point handler is called when a break point or single step break point occurs.

Parameters

hProcess
Identifies an open handle of the process. This member can be used to read from and write to the process's memory via ReadProcessMemory and WriteProcessMemory.

pContext
Points to a CONTEXT structure that contains the context of the thread. The value of the ContextFlags member of this structure is CONTEXT_FULL. When the handler returns, SetThreadContext will be called to update the thread's context with the value of CONTEXT structure upon exit of the handler.

pvUser
User supplied pointer for the break point.

Return Value

The function must return one of the following values:

Value Meaning
BPH_CLEAR
Clears the break point.

BPH_REENABLE
Leaves the break point enabled.

BPH_DISABLE
Disables the break point.
This is not a valid return value for a single step break point handler.

Remarks

See Also

BreakPointSet, SingleStep, FixBugRun, BreakPointClear, BreakPointEnable, BreakPointDisable


Third Eye Software Inc. / 68-20 Fresh Meadow Lane / Flushing, NY 11365
Copyright © 1996-7 Third Eye Software Inc. All rights reserved.
Email: eye3@escape.com
WWW: http://www.escape.com/~eye3/

Page Served At:
Last Modified:
Hits: