Click here to Skip to main content
14,877,136 members
Articles / Programming Languages / C++
Posted 1 Aug 2002


131 bookmarked

Trapping Bugs with BlackBox

Rate me:
Please Sign up or sign in to vote.
3.72/5 (27 votes)
25 May 2003BSD6 min read
A brief article explaining how to use BlackBox in your programs to trap errors

Sample Image - BlackBoxUI.jpg


Have you ever had an application crash on a customer's machine and have only, "it just crashes and displays a funny message box", to go on in attempting to track down what the error was? Ever wish you could put some kind of "watchdog" that would monitor your application on the customers computer and then if it crashed, automatically scoop up where the crash happened, and allow the customer or mail this information to you? If so then BlackBox may be just what you're looking for! 

BlackBox (which I have since discovered is the name of a window manager for linux, so if anyone has any ideas about a better name, please feel free to let me know :) ) is a dll that you simply load up and then forget about. It will set a crash handler as soon as the library is loaded (in DLLMain()), and then just waits patiently for your application to crash. If and/or when your application crashes, instead of just displaying an error message like "Error writing to memory address 0XDEADBEEF", a nice little dialog comes up that displays the information in a fashion similar to Netscape's TalkBack, or the new error reporting dialog that pops up with the newer version of Microsoft's Internet Explorer. This dialog allows the user to then copy or save the crash data, and then email or be taken to an appropriate website where they can submit the information. This information can then be used by a programmer to have a much better idea of exactly where the problem occurred, as well as information about the machine that it crashed on.

It is extremely lighweight as a DLL at only 32 Kb in size, so there is no worry about bloat if you decide to use this!


You can customize the text that is displayed in the main label, by opening BlackBox.cpp and editing the following code:

const char* g_errorLable = 
                "This is my version of BlackBox - An error has occured!
                 You are screwed";

By changing the g_errorLable variable, this will change what is displayed in the label in the top area of the dialog.

In addition, you can customize the email address to use when the "Mail to..." button is clicked, and the URL that is used when the "Submit bug..." button is clicked. Again open BlackBox.cpp and editing the following code:

const char* g_mailToAddress= 
                //change this to something useful 
const char* g_submitBugURL= 
                //change this to something useful 


BlackBox displays a variety of information:

  • The Exception Reason
  • The Registers
  • The Stack Trace, a complete stack trace from where the error occured
  • The machine information, such as CPU, OS version, physical memory, etc. Clicking on the "Information..." button will display this in a dialog.
  • The machine state - a list of ALL the processes running at the time of the crash, and any DLLs loaded by the processes. Clicking on the "State..." button will display this in a dialog.

As a user, you can copy the contents to the clipboard by clicking on the "Copy" button. Clicking the "Save..." button will prompt you to save the contents to a file, with the default name being of the form: "errorlog-<GMT time, dd-mm-yyyy>(<time, hh:mm:ss>).log".

Click the "Mail To..." button and an attempt will be made to execute the mailto: command on your system. Assuming a properly installed email program, it will be brought up with the appropriate email address. See above for configuring these two features.

The basics of the code is "stolen" from John Robbins excellent book Debugging Applications that show how to do all sorts of gory low level things, among them performing a stack trace. To get the stack trace to provide something useful, however, you may have to make some modifications to your build settings for release builds. The stack tracing relies on certain system calls, as well as information in the executable itself. If the executable is a release build, then there will be almost no debug information, and as a result, your stack trace will show almost nothing, which for me, at least, is one of the critical reasons why I wrote this tool. To allow the symbol engine to successfully display information, you need to enable the generation of debug information (/debug) in the linker settings (you do NOT need to do this in your code generation or C++ settings), and you need to tell the linker to generate a mapfile (/map ["filename"] ). Then when you distribute your application make sure to also put the BlackBox.dll and the map file(typically the map file is the same name as the executable, but with a ".map" extension) in the same directory as your exe. Obviously this does mean you are "exposing" a bit more information to people (i.e. your customers), but the tradeoff is readable stack trace information that can be invaluable in locating where a crash happened. BlackBox will still work with an executable that does not supply a map file or linker debug information, it will just not display as much information.


To actually use this in your application, you only need to do the following:

HINSTANCE hLib = LoadLibrary( "BlackBox.dll" );

That's it! To be a good Win32 citizen, you should unload the library when your app exits:

if ( NULL != hLib ) {
    FreeLibrary( hLib );

Everything else is handled internally in the BlackBox library.

One final note: To build this code you will need the latest Platform SDK (at least from the last year or so). In addition, when you put this out in the wild, so to speak, you will need to distribute the psapi.dll and the dbghelp.dll dll's for this to all work, they are part of what allows the symbol engine to work.

To Do:

In the near future I would like to add support for encrypting the data, right now it is just plain text, and this may not be appropriate in certain cases. I would also like to write a server program that would run on a machine, and to which the BlackBox client program could simply send the encrypted data via sockets.

Further Customization:

Should you wish to do more radical customizations, the core UI code is all contained in the BlackBoxUI.cpp. This is what allocates all the memory, which is done using GlobalXXX functions, as we may not be able to use the local heap. The starting point for all of this is the ShowBlackBoxUI() function, which sets up all the information and then displays the main dialog.


John Robbins, Debugging Applications, Microsoft Press; ISBN: 0735608865, 2000

See this for more information about John Robbins at Wintellect.

The display code for the various processes was based on work that Emmanuel Kartmann did in his article Display Loaded Modules


The BlackBox dll is part of the toolset created for the Visual Component Framework. For further updates please see the VCF project page and either check the CVS status or look at the files section for the newest BlackBox file release.


This article, along with any associated source code and files, is licensed under The BSD License


About the Author

Jim Crafton
Software Developer (Senior)
United States United States
Currently working on the Visual Component Framework, a really cool C++ framework. Currently the VCF has millions upon millions upon billions of Users. If I make anymore money from it I'll have to buy my own country.

Comments and Discussions

QuestionException occurs but BlackBox not activated Pin
bigkim16-Aug-11 6:46
Memberbigkim16-Aug-11 6:46 
GeneralError in bool OnCopyToClipboardData( HWND hDlg ) function Pin
alexptt14-Jan-09 3:42
Memberalexptt14-Jan-09 3:42 
GeneralStatic library vs. DLL Pin
suggam20-May-08 7:47
Membersuggam20-May-08 7:47 
QuestionWhere's the DLL? Pin
Manaxter12-Dec-06 17:37
MemberManaxter12-Dec-06 17:37 
GeneralRe: Where's the DLL? Pin
jason_pei21-Apr-08 19:02
Memberjason_pei21-Apr-08 19:02 
Generalproblem in stack look up. Pin
Dinesh 3067820-Sep-06 19:12
MemberDinesh 3067820-Sep-06 19:12 
Questionmemmory Issuse Pin
yifuwong12-Sep-06 18:52
Memberyifuwong12-Sep-06 18:52 
GeneralBlackbox and VB6 Pin
ivanmdeb2-Apr-05 18:32
Memberivanmdeb2-Apr-05 18:32 
GeneralRe: Blackbox and VB6 Pin
Jim Crafton3-Apr-05 6:02
MemberJim Crafton3-Apr-05 6:02 
GeneralSource Code Licensing and Terms Pin
lmemmott25-Feb-05 17:35
Memberlmemmott25-Feb-05 17:35 
GeneralRe: Source Code Licensing and Terms Pin
Jim Crafton26-Feb-05 2:15
MemberJim Crafton26-Feb-05 2:15 
GeneralStack overflows ignored? - ignore this - found the answer in the source Pin
Stuart Dootson16-Nov-04 23:55
professionalStuart Dootson16-Nov-04 23:55 
General.lib not available Pin
Soumik Ghosh16-Nov-04 20:18
MemberSoumik Ghosh16-Nov-04 20:18 
GeneralRe: .lib not available Pin
Jim Crafton18-Nov-04 9:40
MemberJim Crafton18-Nov-04 9:40 
GeneralCool code, very nice! Pin
BaldwinMartin15-Oct-04 15:55
MemberBaldwinMartin15-Oct-04 15:55 
GeneralCrashes are ignored Pin
keith_sabine14-Oct-04 22:10
Memberkeith_sabine14-Oct-04 22:10 
GeneralRe: Crashes are ignored Pin
Jim Crafton15-Oct-04 3:54
MemberJim Crafton15-Oct-04 3:54 
GeneralCrashes aren't catched Pin
Cédric RICARD11-Sep-03 1:46
MemberCédric RICARD11-Sep-03 1:46 
GeneralRe: Crashes aren't catched Pin
Cédric RICARD11-Sep-03 3:39
MemberCédric RICARD11-Sep-03 3:39 
GeneralRe: Crashes aren't catched Pin
Jim Crafton11-Sep-03 15:57
MemberJim Crafton11-Sep-03 15:57 
GeneralRe: Crashes aren't catched Pin
Cédric RICARD12-Sep-03 2:35
MemberCédric RICARD12-Sep-03 2:35 
GeneralRe: Crashes aren't catched Pin
Jim Crafton13-Sep-03 5:15
MemberJim Crafton13-Sep-03 5:15 
GeneralWindows 98 Pin
Anonymous28-Aug-03 5:42
MemberAnonymous28-Aug-03 5:42 
GeneralRe: Windows 98 Pin
Jim Crafton1-Sep-03 18:21
MemberJim Crafton1-Sep-03 18:21 
GeneralError while compiling.. Pin
Md Saleem Navalur27-Aug-03 12:31
MemberMd Saleem Navalur27-Aug-03 12:31 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.