__debugbreak() Checker

__debugbreak() Checker is a software tool that scans source code looking for calls to __debugbreak() that are not conditionally compiled and that are not conditionally executed. Additional functions names can be specified so that you can search for your own functions that implement similar behaviour.

Why? What’s the point?

At Software Verify, we use _debugbreak() and other calls in our code to embed places where we can interact with the user to allow us to attach to a debugger in situations that would be almost impossible to do manually (for example, at the point where we’re injecting code inside the target program). These are controlled be feature flags, which are OFF by default.

Sometimes we temporarily add these calls to allow us to inspect an interaction. We then remove them once the work is done. The temporary usage is not protected by a feature flag conditional or by conditional compilation. That makes searching for them straightforward if you have a tool like __debugbreak() Checker.

Leaving these calls in your program will trigger breakpoint exceptions if they are executed. This will change the behaviour of the program (assuming they are caught by an exception handler) and possibly result in the program crashing completely (when they are not caught by an exception handler).

__debugbreak() Checker provides a GUI for interactive discovery of __debugbreak() calls and also a command line so that you can automate this and drop it into your smoke tests, regression tests, continuous integration tests.

Filters are provided so that calls that are valid are ignored and only the calls that shouldn’t be in the code are flagged for your attention.

Couldn’t I just search for these in my text editor?

Yes, you could. But you’d get a listing showing every usage of __debugbreak(), regardless of conditional compilation, and regardless of conditional execution. That forces you to manually check each one, rather than just look at the ones that you didn’t expect to find.

Software engineers are human, and mistakes get made, people get tired, they can forget to remove the temporary code. This tool is here to make identifying such mistakes easier.

__debugbreak() Checker scans all source files under a specified disk hierarchy. When function calls are found that match the criteria specified in the settings the usage is reported on the function report.

In the function report shown above 15 matches have been found for __debugbreak() criteria that match the settings.

Clicking on an entry in the function report will show the source code in the source code viewer. The line of interest is highlighted in green.

Double clicking on an entry in the function report will start Visual Studio to edit the source code.

Command line

You can automate this checking by using __debugbreak() Checker from the command line. Add automated checking to your code review process, source code check in process, or to your software release process.

Example 1 Scan a directory and output the results to a log file. If there are no results, there will be no log file.

debugBreakChecker.exe /dir e:\om\c\ 
                      /output e:\test.txt

Example 2 Scan a directory looking for a custom debugging function and output the results to a log file. If there are no results, there will be no log file.

debugBreakChecker.exe /dir e:\om\c\ 
                      /output e:\test.txt 
                      /removeAllFunctions 
                      /addFunction myDebuggingFunction