Insure++ 6.0 for
Windows NT/2000

Readme Contents

• Chaperon
  
• Visual C++ Integration
  
• InsureSpy Integrated Debugging
  
• Setting a Breakpoint at Runtime Errors
  
• Command Line
  
• Creating an Insure Configuration
  
• Precompiled Headers
  
• Running Your Program
  
• COM objects, Windows Services, and Child Processes
  
• Using TCA
  
• Using Inuse
  
• Obtaining and Installing a Product License
  
• Contacting Technical Support
  

Chaperon

Chaperon works with existing executable programs, not instrumented executables. In most cases, Chaperon requires no recompilation and no relinking, and no changes to environment variables.

Chaperon checks all data memory references made by a process, whether in the developer's compiled code, language support routines, or shared or archive libraries. Chaperon detects and reports reads of uninitialized memory, reads or writes that are not within the bounds of allocated blocks, and allocation errors such as memory leaks.

When Chaperon detects improper behavior, it issues an error message identifying the kind of error and where it occurred. Improper behavior is considered to be any access to a logically unallocated region, a Read (or Modify) access to bytes which have been allocated but not yet Written, and errors or abuses of the malloc/free protocol, such as attempting to free the same block twice.

Chaperon also detects memory blocks that have been allocated and not freed. Such a block is "in use." If a block is in use and unreachable by starting from the stack, or statically allocated regions, and proceeding through already reached allocated blocks, then the block is a "memory leak." The block could not be freed without some oracle to specify its address as the parameter to free(). At exit() Chaperon reports memory leaks automatically.

Note: Insure++ does not report coverage information in Chaperon mode.

Running

To run Insure++ in Chaperon mode, perform these steps.

1. Open the file or workspace in Developer Studio.
2. Click the Insure++ Control Panel icon to open the Insure++ Control Panel.
3. In the General tab, make sure the option Chaperon checking is not enabled.
4. In the Developer Studio window, choose Build> Rebuild All.

Note: Do not make an instrumented build of the file.

5. Run the program under InsureSpy by clicking the Insure++ Execute icon.

To stop Insure++ while in progress, click the Stop Build icon.

To view and/or change Insure++ options, click the Insure++ Control Panel icon.

By default, error messages are sent to Insra. For more information see Insra.

For more methods of running Insure++ see Running Insure++.

Visual C++ Integration

	Instrument File: Instruments and compiles the selected source file.
	Insure++ Build: Instruments and compiles all files do not have up-to-date object files. (This must be done after files are instrumented with Instrument File.)
	Insure++ Rebuild All: Cleans and rebuilds with instrumentation.
	Insure++ Stop Build: Aborts any of the first three buttons.
	Insure++ Execute: Executes the selected program with Insure++.
	Insure++ Debug: Runs the Microsoft debugger and Insure++.
	Insure++ Control Panel: Invokes Insure++ Control Panel.
	Insra: Invokes Insra.
	Inuse: Invokes Inuse
	TCAview: Invokes TCAview, the TCA GUI.

Note that the first four buttons correspond to the buttons under the Build heading of DevStudio. The only difference is that your files will be instrumented by Insure++ and linked against Insure++ libraries.

All of the above commands can also be accessed in the tools menu of Visual C++.

InsureSpy Integrated Debugging

This feature enables the user to get runtime error-detection from Insure++ while running in the Microsoft Debugger (msdev.exe). This feature is available for Developer Studio Version 6.0.

When Insure++ is installed, running an instrumented executable (a .exe file that is built with Insure++) through the debugger will automatically invoke the integrated version of InsureSpy. No special settings are required for this behavior. When running a NON-INSTRUMENTED executable through the debugger, the default behavior is that InsureSpy is NOT invoked, i.e., the debugger operates as it did before Insure++ was installed. Sometimes it is desirable to invoke the integrated InsureSpy on non-instrumented executables.

Examples:

• Minimal error detection is desired without rebuilding the application and integrated debugging is desired.
• The instrumented module is a component such as a DLL or OCX which is loaded into a non-instrumented executable and integrated debugging is desired.

In these cases, the integrated InsureSpy can be invoked by selecting Automatic InsureSpy Integrated Debugging in the General tab of the Insure++ Control Panel. When this box is checked, all executables that are started in the debugger will be run through the integrated InsureSpy. Another way to run all executables (instrumented or not) through the debugger and InsureSpy, is to simply click the Insure++Debug button in the Insure++ tool bar.

Also note that this option does not affect running InsureSpy outside of the debugger (e.g., running Insure++ by clicking Insure++ Execute, selecting File> Run in Insra, or calling InsureSpy or inject explicitly from the command-line or from Image file execution options, as described in the section Running Insure++).

Setting a Breakpoint at Runtime Errors

Command Line

Insure++ can be run from the command line as well. When using nmake, just have:

 
CPP=insure.exe
LINK32=inslink.exe

Creating an Insure++ Configuration

If you are building large projects with Insure++, you might want to make an Insure++ configuration of your project. Such a configuration would allow you to switch back and forth between instrumented and non-instrumented versions of your program without recompiling all of your source files.

To create an Insure++ configuration, perform the following steps:

1. In Developer Studio, select Configurations from the Build menu.
2. Select the desired project and click Add.
3. In the Configuration field, enter Insure.
4. In the Copy settings from: field, select the debug configuration.
5. In the Settings for: field, select the platform (Win32).
6. Click OK.
7. Click Close.

Developer Studio will then select a default output directory for this configuration. You should change this by performing the following steps:

1. Select Settings from the Project menu.
2. In the Settings for field, select Win32 Insure.
3. In the General Tab, enter Insure in both the Intermediate files field and the Output files field.

After you complete these procedures, you will be able to switch back and forth between "Debug" and "Insure" configurations without rebuilding your projects.

Precompiled Headers

Insure++ supports the use of precompiled headers. However, here are some subtleties to be aware of.

In a project WITHOUT precompiled headers, if all the object files are up to date and non-instrumented, a single file can be instrumented, then the project can be relinked using insure++ build. However, if precompiled headers are used, and all the object files are up to date but non-instrumented, then instrumenting a single file will cause the precompiled header to be instrumented. This touches the time-stamp on the precompiled header, so all the object files are now out of date with respect to the precompiled header. When an insure++ build is done, a full rebuild will be triggered.

One solution to this is to create an Insure++ Configuration (see "Creating an Insure++ Configuration" above) that uses precompiled headers. Another solution is to not use precompiled headers. The recommended solution is to have an Insure++ Configuration and to disable precompiled headers for the Insure Configuration. (This solution is not possible in some MFC AppWizard generated projects, which are designed to only be built with pre-compiled headers.)

Running Your Program

For runtime error detection on both instrumented and non-instrumented programs, always run with InsureSpy through one of the following methods:

• From within DevStudio, select Insure++ Execute, which is the blue ! button on the Insure++ toolbar.
• From within DevStudio, choose Go or press F5 to run through the debugger. If the executable is instrumented with Insure++, an integrated version of InsureSpy will automatically be invoked in the Microsoft Debugger. To use the integrated InsureSpy with a non-instrumented program this way, simply select Automatic InsureSpy Integrated Debugging from the General tab of the Insure++ Control Panel.
• From Insra, choose File> Run.
  Browse for the executable and it will be run with Insure++. The messages will automatically be sent to Insra.
• From the command line, the bin.Win32 directory of your Insure++ installation will need to be on your PATH. Then type:

  	insurespy foo

  This will run foo.exe with insurespy. This version uses Message Boxes. A text-only version is called inject. To run inject, type:

  	inject foo

COM objects, Services, and Child Processes

Some applications must be invoked in atypical ways. For example, Services may be executed by the service control manager. ActiveX controls may be loaded into other executables spawned automatically. Child processes may be executed by calls to CreateProcess from parent processes.

In these cases, the "Image File Execution" can be used on Windows NT/2000 to run the program through InsureSpy. In the Insure++ Control Panel, on the Advanced tab, enter your executable name (without a path) under "Image File Execution Options: Executable". Select InsureSpy.exe for the debugger. If you wish to use InsureSpy integrated in the Microsoft debugger, select msdev.exe instead of InsureSpy.

Note: This mechanism is provided by the Windows NT/2000 operating system. The window into this mechanism provided in the Insure++ Control panel is for your convenience. If you prefer, you can alter the registry keys directly:

HKEY_LOCAL_MACHINE/Software/Microsoft/WindowsNT/CurrentVersion/"Image File Execution Options"/

When you are done debugging the executable with Insure++, be sure to remove the executable name from the list, or InsureSpy.exe will be invoked every time that executable runs.

When debugging a Windows Service with Insure++, allow the service to interact with the desktop. This is a checkbox for service option in the service control manager. Also, because the Windows service will be running as a system process, you must have [Insure++_Install_Dir]/bin.Win32 on your system PATH environment variable. It is not sufficient to have it on your user PATH environment variable.

See also [Insure++ Install dir]/examples/service_demo.txt for an example of running Insure++ on an Windows Service application.

Using TCA (Total Coverage Analysis)

Insure++ tracks code coverage information in a file called tca.log. This file is located in the same directory as your program.

Note: If you want Insure++ to generate coverage information, you must enable the Generate coverage map data option in the Compile tab of the Insure++ Control Panel. You can analyze Insure++ coverage from the command line or with the TCA add-on GUI. To review code coverage information from the TCA GUI:

1. Click the TCAview icon in the Windows Start menu or the DevStudio toolbar
2. Click File> Load in the TCA window and select the tca.log file located in your program's directory.

To review code coverage information from the command line, type:

tca tca.log

To get a list of command line tca options, type:

tca

Using Inuse

To use Inuse to see a graphic display of how your program uses dynamic memory, compile your program without insure. Then choose Start> Programs> Insure++> Inuse.

The Inuse GUI will appear. From the GUI, choose File> Run.

Then browse for the executable that you built with Visual C++. At this point you should be able to view your program's memory from within Inuse.

Obtaining and Installing a Product License

Once you install Insure++, you need to enter a password and expiration date before you can begin using the tool.

To receive your password and expiration date, call ParaSoft at 1-888-305-0041.

You will need to give the Machine and Machine ID information to the representative in order to receive your password and expiration date. This information is located in InsurePanel> Password. (You can access this tab by clicking Insure++ Control Panel, then clicking the Password tab)

Once you receive your password and expiration date, enter them into the Password and Expiration date fields and click OK. You can now begin using Insure++.

Contacting Technical Support

email: support@parasoft.com
phone: (888) 305-0041

Contacting ParaSoft