Click here to Skip to main content
Click here to Skip to main content

Trapping Bugs with BlackBox

, 25 May 2003 BSD
Rate this:
Please Sign up or sign in to vote.
A brief article explaining how to use BlackBox in your programs to trap errors
<!-- Article image -->

Sample Image - BlackBoxUI.jpg

<!-- Add the rest of your HTML here -->


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 Smile | :) ) 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 Pinmemberbigkim16-Aug-11 7:46 
GeneralError in bool OnCopyToClipboardData( HWND hDlg ) function Pinmemberalexptt14-Jan-09 4:42 
GeneralStatic library vs. DLL Pinmembersuggam20-May-08 8:47 
QuestionWhere's the DLL? PinmemberManaxter12-Dec-06 18:37 
GeneralRe: Where's the DLL? Pinmemberjason_pei21-Apr-08 20:02 
in the Superiors directory ../
Generalproblem in stack look up. PinmemberDinesh 3067820-Sep-06 20:12 
Questionmemmory Issuse Pinmemberyifuwong12-Sep-06 19:52 
GeneralBlackbox and VB6 Pinmemberivanmdeb2-Apr-05 19:32 
GeneralRe: Blackbox and VB6 PinmemberJim Crafton3-Apr-05 7:02 
GeneralSource Code Licensing and Terms Pinmemberlmemmott25-Feb-05 18:35 
GeneralRe: Source Code Licensing and Terms PinmemberJim Crafton26-Feb-05 3:15 
GeneralStack overflows ignored? - ignore this - found the answer in the source PinmemberStuart Dootson17-Nov-04 0:55 
General.lib not available PinmemberSoumik Ghosh16-Nov-04 21:18 
GeneralRe: .lib not available PinmemberJim Crafton18-Nov-04 10:40 
GeneralCool code, very nice! PinmemberBaldwinMartin15-Oct-04 16:55 
GeneralCrashes are ignored Pinmemberkeith_sabine14-Oct-04 23:10 
GeneralRe: Crashes are ignored PinmemberJim Crafton15-Oct-04 4:54 
GeneralCrashes aren't catched PinsussCédric RICARD11-Sep-03 2:46 
GeneralRe: Crashes aren't catched PinsussCédric RICARD11-Sep-03 4:39 
GeneralRe: Crashes aren't catched PinmemberJim Crafton11-Sep-03 16:57 
GeneralRe: Crashes aren't catched PinsussCédric RICARD12-Sep-03 3:35 
GeneralRe: Crashes aren't catched PinmemberJim Crafton13-Sep-03 6:15 
GeneralWindows 98 PinsussAnonymous28-Aug-03 6:42 
GeneralRe: Windows 98 PinmemberJim Crafton1-Sep-03 19:21 
GeneralError while compiling.. PinmemberMd Saleem Navalur27-Aug-03 13:31 
GeneralRe: Error while compiling.. PinmemberJim Crafton1-Sep-03 19:23 
GeneralRe: Error while compiling.. Pinmemberkanger30-Dec-04 1:17 
GeneralQuestion PinsussAnonymous4-Jul-03 1:40 
GeneralRe: Question PinmemberJim Crafton4-Jul-03 7:03 
GeneralTip: if you don't want to distribute your MAP-file PinmemberSimon Hofverberg2-Jun-03 22:42 
GeneralRe: Tip: if you don't want to distribute your MAP-file Pinmemberjason_pei8-Dec-06 0:06 
GeneralBlackBox revised PinsussAnonymous29-May-03 0:52 
GeneralMinor bug PinmemberTaka Muraoka25-May-03 21:59 
GeneralRe: Minor bug PinmemberJim Crafton26-May-03 4:31 
GeneralWhere to find updates Pinmemberstugots18-May-03 16:28 
GeneralRe: Where to find updates PinmemberJim Crafton19-May-03 4:30 
GeneralRe: Where to find updates Pinmemberstugots19-May-03 8:51 
GeneralSuggestions PinsitebuilderUwe Keim8-Dec-02 7:34 
GeneralRe: Suggestions Pinmembermr_snrub13-Jan-03 19:07 
GeneralRe: Suggestions PinmemberJim Crafton14-Jan-03 5:03 
GeneralMAP or PDB PinmemberAlexanderAC21-Aug-02 18:55 
GeneralRe: MAP or PDB PinmemberJim Crafton22-Aug-02 4:14 
GeneralRe: MAP or PDB PinmemberJediMaster24-Aug-02 13:00 
GeneralRe: MAP or PDB PinmemberBrad Bruce10-Jan-03 10:07 
GeneralRe: MAP or PDB Pinmemberjlanawalt7-Aug-07 8:50 
Questionwhat about accompanying dlls? Pinmemberkstewart20-Aug-02 7:33 
AnswerRe: what about accompanying dlls? PinmemberJim Crafton20-Aug-02 18:31 
GeneralRe: what about accompanying dlls? Pinmemberkstewart5-Sep-02 8:14 
QuestionHow do I... PinmemberDarren Schroeder7-Aug-02 3:00 
AnswerRe: How do I... PinmemberJim Crafton7-Aug-02 4:33 

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

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

| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.150327.1 | Last Updated 26 May 2003
Article Copyright 2002 by Jim Crafton
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid