Click here to Skip to main content
13,146,014 members (44,466 online)
Click here to Skip to main content
Add your own
alternative version


130 bookmarked
Posted 1 Aug 2002

Trapping Bugs with BlackBox

, 25 May 2003
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 :) ) 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:

<PRE lang=c++>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.

You may also be interested in...

Comments and Discussions

GeneralRe: Error while compiling.. Pin
Jim Crafton1-Sep-03 18:23
memberJim Crafton1-Sep-03 18:23 
GeneralRe: Error while compiling.. Pin
kanger30-Dec-04 0:17
memberkanger30-Dec-04 0:17 
GeneralQuestion Pin
Anonymous4-Jul-03 0:40
sussAnonymous4-Jul-03 0:40 
GeneralRe: Question Pin
Jim Crafton4-Jul-03 6:03
memberJim Crafton4-Jul-03 6:03 
GeneralTip: if you don't want to distribute your MAP-file Pin
Simon Hofverberg2-Jun-03 21:42
memberSimon Hofverberg2-Jun-03 21:42 
GeneralRe: Tip: if you don't want to distribute your MAP-file Pin
jason_pei7-Dec-06 23:06
memberjason_pei7-Dec-06 23:06 
GeneralBlackBox revised Pin
Anonymous28-May-03 23:52
sussAnonymous28-May-03 23:52 
GeneralMinor bug Pin
Taka Muraoka25-May-03 20:59
memberTaka Muraoka25-May-03 20:59 
GeneralRe: Minor bug Pin
Jim Crafton26-May-03 3:31
memberJim Crafton26-May-03 3:31 
GeneralWhere to find updates Pin
stugots18-May-03 15:28
memberstugots18-May-03 15:28 
GeneralRe: Where to find updates Pin
Jim Crafton19-May-03 3:30
memberJim Crafton19-May-03 3:30 
GeneralRe: Where to find updates Pin
stugots19-May-03 7:51
memberstugots19-May-03 7:51 
GeneralSuggestions Pin
Uwe Keim8-Dec-02 6:34
sitebuilderUwe Keim8-Dec-02 6:34 
GeneralRe: Suggestions Pin
mr_snrub13-Jan-03 18:07
membermr_snrub13-Jan-03 18:07 
GeneralRe: Suggestions Pin
Jim Crafton14-Jan-03 4:03
memberJim Crafton14-Jan-03 4:03 
GeneralMAP or PDB Pin
AlexanderAC21-Aug-02 17:55
memberAlexanderAC21-Aug-02 17:55 
GeneralRe: MAP or PDB Pin
Jim Crafton22-Aug-02 3:14
memberJim Crafton22-Aug-02 3:14 
GeneralRe: MAP or PDB Pin
JediMaster24-Aug-02 12:00
memberJediMaster24-Aug-02 12:00 
GeneralRe: MAP or PDB Pin
Brad Bruce10-Jan-03 9:07
memberBrad Bruce10-Jan-03 9:07 
GeneralRe: MAP or PDB Pin
jlanawalt7-Aug-07 7:50
memberjlanawalt7-Aug-07 7:50 
Questionwhat about accompanying dlls? Pin
kstewart20-Aug-02 6:33
memberkstewart20-Aug-02 6:33 
AnswerRe: what about accompanying dlls? Pin
Jim Crafton20-Aug-02 17:31
memberJim Crafton20-Aug-02 17:31 
GeneralRe: what about accompanying dlls? Pin
kstewart5-Sep-02 7:14
memberkstewart5-Sep-02 7:14 
QuestionHow do I... Pin
Darren Schroeder7-Aug-02 2:00
memberDarren Schroeder7-Aug-02 2:00 
AnswerRe: How do I... Pin
Jim Crafton7-Aug-02 3:33
memberJim Crafton7-Aug-02 3:33 
GeneralPoblem with getting it to work! :( Pin
Anonymous5-Aug-02 7:10
sussAnonymous5-Aug-02 7:10 
GeneralRe: Poblem with getting it to work! :( Pin
Jim Crafton5-Aug-02 9:52
memberJim Crafton5-Aug-02 9:52 
GeneralRe: Poblem with getting it to work! :( Pin
Anonymous5-Aug-02 11:48
sussAnonymous5-Aug-02 11:48 
GeneralRe: Poblem with getting it to work! :( Pin
anamnesis1-Sep-03 0:15
memberanamnesis1-Sep-03 0:15 
QuestionCan't work, why? Pin
gong_xc@hotmail.com5-Aug-02 3:37
sussgong_xc@hotmail.com5-Aug-02 3:37 
AnswerRe: Can't work, why? Pin
Jim Crafton5-Aug-02 7:07
memberJim Crafton5-Aug-02 7:07 
AnswerRe: Can't work, why? Pin
Colin Urquhart5-Aug-02 14:16
memberColin Urquhart5-Aug-02 14:16 
GeneralRe: Can't work, why? Pin
Jim Crafton5-Aug-02 18:01
memberJim Crafton5-Aug-02 18:01 
GeneralRe: Can't work, why? Pin
Colin Urquhart5-Aug-02 20:13
memberColin Urquhart5-Aug-02 20:13 
GeneralA Bit of a Problem Pin
Joel Matthias4-Aug-02 18:32
memberJoel Matthias4-Aug-02 18:32 
GeneralRe: A Bit of a Problem Pin
Jim Crafton5-Aug-02 2:38
memberJim Crafton5-Aug-02 2:38 
GeneralRe: A Bit of a Problem Pin
Joel Matthias5-Aug-02 5:12
memberJoel Matthias5-Aug-02 5:12 
GeneralWheatyExceptionReport also worth a look Pin
Neville Franks3-Aug-02 13:39
memberNeville Franks3-Aug-02 13:39 
GeneralProject doesn't compile Pin
Tony Fontenot2-Aug-02 18:59
memberTony Fontenot2-Aug-02 18:59 
GeneralRe: Project doesn't compile Pin
Anonymous3-Aug-02 1:01
sussAnonymous3-Aug-02 1:01 
GeneralRe: Project doesn't compile Pin
Jim Crafton3-Aug-02 4:49
memberJim Crafton3-Aug-02 4:49 
GeneralRe: Project doesn't compile Pin
Tony Fontenot3-Aug-02 9:15
memberTony Fontenot3-Aug-02 9:15 
GeneralWe use the minidump Pin
Tim Smith2-Aug-02 16:46
memberTim Smith2-Aug-02 16:46 
GeneralRe: We use the minidump Pin
Jim Crafton2-Aug-02 17:39
memberJim Crafton2-Aug-02 17:39 
GeneralRe: We use the minidump Pin
Tim Smith4-Aug-02 6:12
memberTim Smith4-Aug-02 6:12 

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.

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