This section lists the options you can use when you instrument and run native-compiled (unmanaged) Visual C/C++ programs from the command line.
Command-line option conventions:
§ If a yes or no option is specified and a value is not explicitly given, Purify assumes the value to be yes.
§ Most options have equivalents in Purify dialog boxes, or can be specified in Additional options in the Files tab in the settings dialog boxes. Options that can be set only in the command line are indicated in the list below with an asterisk (*).
§ Options you specify in the command line override any settings that were saved from the Purify user interface.
§ Options you specify in the command line apply only to the current run of the program; they are not saved, and will not subsequently appear in the user interface.
§ A double asterisk (**) indicates an option that is valid only when you have Rational PureCoverage installed and when you specify the /Coverage option with the purify command, to collect coverage data for the run.
§ For command-line option syntax, click
/AutoMergeData * **
/Coverage **
/CoverageDefaultInstrumentationType **
/Help *
/PurifyDefaultInstrumentationType
/Replace *
/Run *
/ShowInstrumentationProgress *
/Usage *
/Version *
/? *
filename.cfy * **
filename.pcy * **
filename.pfy *
/AllocCallStackLength=<integer>
Specifies the maximum number of call stack levels Purify records for allocation locations corresponding to errors found in the program. For example:
purify /AllocCallStackLength=5 myapp.exe
By default, Purify specifies an allocation call stack level of 10.
/AllowDialogOnAssert=yes|no
Specifies whether to allow the Assert dialog box to be displayed for program execution errors. For example:
purify /AllowDialogOnAssert=yes myapp.exe
By default, the Assert dialog box is not displayed.
/AutoMergeData=yes|no
Specifies whether Purify creates an Auto Merge run when you monitor a program, and automatically updates the run with data from subsequent runs of the program. For example:
purify /Coverage /AutoMergeData=no myapp.exe
By default, Purify creates an Auto Merge run and appends the run with data from subsequent runs of the program.
Note: If you specify /AutoMergeData=no with the /SaveMergeData option, Purify creates an Auto Merge run and saves the data to a PureCoverage data file (.cfy). If an identically named .cfy file already exists, Purify automatically overwrites the file. This effectively writes single run data to the <filename_AutoMerge.cfy> file (or overwrites it if it already exists).
Command line only option.
/CacheDir=<directory>
Specifies the directory where you want Purify to store instrumented versions of executable and module files. For example:
purify /CacheDir="C:\MyProjects\MyappDir\Cache" myapp.exe
By default, Purify uses its own cache directory. For information about the files Purify creates and their locations, click
/CollectionGranularity=line|function|exclude
or
/CoverageDefaultInstrumentationType=line|function|exclude
Specifies the instumentation level (line, function, or exclude) you want Purify to use for collecting coverage data. The instrumentation level applies to all modules in the program (except those in the Windows directories, to which the /ExcludeSystemDir option can apply). For example:
purify /CoverageDefaultInstrumentationType=function myapp.exe
By default, Purify uses line for all modules except those in the Windows directories, and certain other modules that are always excluded. Purify also excludes modules for which debug line data and relocation data is not available. For more information about Purify's coverage instrumentation levels, click
/Coverage=yes|no
Specifies whether you want Purify to collect coverage data as well as error data for the run. For example:
purify /Coverage myapp.exe
By default, Purify does not collect coverage data when you run an executable (.exe) from the command line. Purify is able to collect coverage data only if you have Rational PureCoverage installed.
§ Command line only option.
/CoverageExcludeMust=<module1;module2;module3;...>
Specifies modules that you want Purify to exclude from coverage. Purify does not record coverage data for excluded modules, and the modules do not appear in any coverage data windows.
purify /CoverageExcludeMust=intellimouse.dll myapp.exe
/CoverageFunctionMust=<module1;module2;module3;...>
Specifies modules that you want Purify to instrument for coverage monitoring at the function level. For example:
purify /CoverageFunctionMust=my_other.dll;myapp.dll myapp.exe
By default, Purify instruments modules using the default coverage level specified in the /CoverageDefaultInstrumentationType option when possible. For more information about how Purify instruments modules for coverage, click
/CoverageLineMust=<module1;module2;module3;...>
Specifies modules that you want Purify to instrument for coverage monitoring at the line level. For example:
purify /CoverageLineMust=my_other.dll;myapp.dll myapp.exe
By default, Purify instruments modules using the default coverage level specified in the /CoverageDefaultInstrumentationType option when possible. For more information about how Purify instruments modules for coverage, click
/ErrorCallStackLength=<integer>
Specifies the maximum number of call stack levels Purify records for error locations in the program. This setting affects whether two errors are considered identical (those with the same message type and error location call stack) and displayed as one message with a count of repeated occurrences, or considered different and displayed as separate messages. For example:
purify /ErrorCallStackLength=5 myapp.exe
By default, Purify specifies an error call stack level of 15 at maximum call stack detail, and 10 at Purify's default call stack detail.
/ExcludeSystemDir=yes|no
Specifies whether to exclude from coverage monitoring all modules in the Windows directories. For example:
purify /ExcludeSystemDir=no myapp.exe
By default, Purify excludes these modules and does not collect any coverage data.
/FilterFiles=<filename1.pft;filename2.pft;filename3.cft...>
Specifies the Purify filter files (.pft) or PureCoverage filter files (.cft) you want Purify to use to filter data from the resulting analysis dataset that it saves to a text file. To specify multiple files, separate them with semicolons. For example:
purify /SaveTextData /FilterFiles=myapp_exe.pft;C:\testapp\myapp_exe.cft myapp.exe
Purify monitors Myapp.exe and uses the filter files Myapp_exe.pft and Myapp_exe.cft to filter the analysis data.
§ Command line only option.
/FirstOnly=yes|no
Displays only the first occurrence of a message with a count of repeated, identical occurrences (those with the same error type and error location call stack), or instead displays each occurrence as a separate message. For example:
purify /FirstOnly=no myapp.exe
By default, Purify displays only the first occurrence of a message with a count of repeated, identical occurrences.
/FreeQueueLength=<integer>
Specifies the number of freed blocks of memory Purify retains in the deferred free queue. For example:
purify /FreeQueueLength=500 myapp.exe
By default, Purify retains 1000 blocks of memory.
/FreeQueueThreshold=<integer>
Specifies the maximum memory block size Purify retains in the deferred free queue. If any freed block is larger, Purify releases it immediately. For example:
purify /FreeQueueThreshold=1000 myapp.exe
By default, Purify retains blocks up to 10000 bytes.
/HandlesInUseAtExit=yes|no
Specifies whether Purify searches for and displays any handles that were in use when you exited the program. For example:
purify /HandlesInUseAtExit=yes myapp.exe
By default, Purify does not search for and display handles in use at exit.
/HeapDestroyLeakScan=0|1|2
Specifies when you want Purify to scan for leaks.
0 |
Scan heaps on exit only. |
1 |
Scan on every heap destroy. |
2 |
Never scan on heap destroy. |
By default, Purify scans for leaks when you exit a program.
When you exit a program, the HeapDestroy API causes a leak scan to occur before the indicated heap is erased. While HeapDestroy does clean up all of the memory in the indicated heap, there could still be a recurring leak in a module that is called by your program; in a .dll or ATL code, for example.
/Help
Displays the syntax for command-line options.
§ Command line only option.
/InUseAtExit=yes|no
Specifies whether Purify searches for and displays any memory blocks that were in use when you exited the program. For example:
purify /InUseAtExit=yes myapp.exe
By default, Purify does not search for and display memory in use at exit.
/LeaksAtExit=yes|no
Specifies whether Purify searches for and displays any memory leaks found when you exited the program. For example:
purify /LeaksAtExit=no myapp.exe
By default, Purify searches for and displays memory leaks at exit.
/MaxDetailChain=yes|no
Specifies whether Purify records call stack data at the maximum, or highest level of detail available for a program. For example:
purify /MaxDetailChain=yes myapp.exe
By default, Purify does not record call stack data at maximum detail.
When /MaxDetailChain=yes, Purify records call stack data for your program and all functions that are invoked by your program, including system functions.
When /MaxDetailChain=no, Purify records call stack data only for functions that were instrumented at precise level, and for Windows APIs.
Purify records call stack data up to the maximum call stack levels specified by /ErrorCallStackLength for error locations, and /AllocCallStackLength for allocation locations.
/Out=<path>
Specifies the path you want Purify to use for the instrumented version of the program.
If you specify a relative path, Purify stores the instrumented executable in a path relative to the current working directory. For this command-line option, this is the directory you were in when you typed the command. For example, if you type the following at the command line:
D:
cd \Win32app
purify /Out=Cache\Foo_pure.exe C:\Myapp\Bar.exe
Purify instruments C:\Myapp\Bar.exe and stores the instrumented version as D:\Win32app\Cache\Foo_pure.exe.
By default, Purify uses the cache directory, the encoded path of the original file, and other information used by Purify.
/PrintInstallDir
Displays the directory where you installed Purify.
§ Command line only option.
/PurifyDefaultInstrumentationType=precise|minimal|exclude
Specifies the type of error-checking instrumentation (precise, minimal, or exclude) that you want Purify to use to instrument modules. For example:
purify /PurifyDefaultInstrumentationType=minimal myapp.exe
By default, Purify uses precise instrumentation. For more information about how Purify instruments modules for error checking, click
/PurifyExcludeMust=<module1;module2;module3...>
Specifies modules that you want Purify to exclude from error-checking instrumentation. Use this option only when you are investigating a Pure message, or the program you're Purify'ing malfunctions as a result of a DLL being injected into it by another process calling SetWindowsHook(). Typical examples of "hook DLLs" that need to be excluded are special mouse and glidepad drivers. For example:
purify /PurifyExcludeMust=intellimouse.dll myapp.exe
By default, Purify excludes all hook DLLs known at time of shipping. If you find a new DLL that needs to be excluded, please notify Rational Software Technical Support. For more information on contacting Technical Support, click
You can specify this option in the command line, or type it in the Additional options box in the Files tab in the settings dialog boxes.
/PurifyMinimalMust=<module1;module2;module3...>
Specifies modules that you want Purify to instrument for error checking at the minimal level. For example:
purify /PurifyMinimalMust=my_other.dll;myapp.dll myapp.exe
By default, Purify instruments modules using the default instrumentation type specified in the /PurifyDefaultInstrumentation option. For more information about how Purify instruments modules for error checking, click
/PurifyPreciseMust=<module1;module2;module3...>
Specifies modules that you want Purify to instrument for error checking at the precise level. For example:
purify /PurifyPreciseMust=my_other.dll;myapp.dll myapp.exe
By default, Purify instruments modules using the default measurement type specified in the /PurifyDefaultInstrumentation option. For more information about how Purify instruments modules for error checking, click
/RedZoneLength=<integer>
Specifies the number of bytes Purify inserts at the beginning and end of each allocated block of memory at run time. For example:
purify /RedZoneLength=32 myapp.exe
By default, Purify inserts 16 bytes.
/Replace=no|yes
Specifies whether to instrument and run the executable in place, rather than storing the instrumented version in the cache directory. Before instrumenting the executable, a backup copy is created (Exename.exe.original) and saved in the same directory as the original.
This option is especially useful when you want to run a test script or batch file using the instrumented program. For example:
purify /Replace=yes myapp.exe
By default, Purify does not replace the executable.
You can use the /UndoReplace option to restore executables to their original, uninstrumented state.
Note: If you are using Microsoft Windows 2000 or higher, the Windows File Protection feature (WFP) may prevent certain types of files from being replaced. For a workaround to this problem, click .
§ Command line only option.
/Run=no|yes
Specifies whether to instrument a program or module without running it. For example:
purify /Run=no myapp.exe
By default, Purify runs the instrumented executable.
You can create a log file that contains instrumentation information by typing:
purify /Run=no myapp.exe 2 > logfile.txt
Since options you specify in the command line apply only to the current run of the program and are not saved, Purify may generate a warning in certain situations. For example:
purify /Run=no /PurifyDefaultInstrumentationType=minimal myapp.exe
In this example, Purify instruments the C runtime library used by myapp.exe. Myapp.exe loads a dll called mydll.dll which also uses the C runtime library. So, if you open the instrumented myapp.exe directly, the instrumented C runtime library is loaded when the program runs. Then when myapp.exe uses LoadLibrary to load mydll.dll, Purify will try to reinstrument the C runtime library using the precise instrumentation type (as the PurifyDefaultInstrumentationType set on the command line is not applied to this run). Since the C runtime is already loaded, Purify issues the warning: "Could not reinstrument C:\Windows\System32\MSVCRTD.DLL as requested: The process cannot access the file because it is being used by another process."
§ Command line only option.
/RuntimeDataBase=<address>
Specifies the starting, or base, address of the shared memory that Purify allocates to store the coverage data it collects at run time. You can specify the address in hexadecimal or decimal format. For example:
purify /RuntimeDataBase=0x00004096 myapp.exe
The size of the shared memory block that Purify attempts to allocate is set in the /RuntimeDataSize option. If there is not enough free memory at the address you specify, Purify will search upwards from that address for a sufficiently large space.
By default, Purify sets the base address to 0x00000000.
/RuntimeDataSize=<size>
Sets the size of the shared memory that Purify allocates to store the coverage data it collects at run time. You can specify the size in hexadecimal or decimal format. For example:
purify /RuntimeDataSize=0x20000000 myapp.exe
By default, Purify uses a size of 0x04000000(64MB).
/SaveData[=<pfyname.pfy>|<pcyname.pcy>]
Instruments and runs a program and saves the data to a file without displaying any Purify windows. The data is saved in a Purify error data file (.pfy) if you are collecting only error data, or in a Purify error and coverage data file (.pcy) if you are collecting both error and coverage data. For example:
purify /SaveData=myapp1.pfy myapp.exe
or
purify /Coverage /SaveData=myapp1.pcy myapp.exe
If you do not specify a file name, Purify uses <exename>.pfy for an error data file, or <exename>.pcy for an error and coverage data file, and saves the file in the same location as your program.
If an identically named file already exists, Purify automatically overwrites the file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files
§ Command line only option.
/SaveMergeData[=<filename_AutoMerge.cfy>]
Saves the Auto Merge data to a PureCoverage data file (.cfy) without displaying any Purify windows. For example:
purify /SaveMergeData=myapp1_automerge.cfy myapp.exe
If you do not specify a file name, Purify uses <exename>_AutoMerge.cfy and saves the file in the same location as your program.
If an identically named file already exists, Purify automatically merges the new run information into the existing file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files
Note: If you specify /AutoMergeData=no with the /SaveMergeData option, Purify creates an Auto Merge run and saves the data to a PureCoverage data file (.cfy). If an identically named .cfy file already exists, Purify automatically overwrites the file This effectively writes single run data to the <filename_AutoMerge.cfy> file (or overwrites it if it already exists).
Command line only option.
/SaveMergeTextData[=<filename_AutoMerge.txt>]
Saves the Auto Merge data to an ASCII text file (.txt) without displaying any Purify windows. For example:
purify /SaveMergeData /SaveMergeTextData=myapp1_automerge.txt myapp.exe
If you do not specify a file name, Purify uses <exename>_AutoMerge.txt and saves the file in the same location as your program.
If an identically named file already exists, Purify automatically overwrites the file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files
Note: To save a text file with coverage data from the current run and subsequent runs of the program, you must use the /SaveMergeData option with this option. If you do not specify /SaveMergeData, this option has the same effect as /SaveTextData.
§ Command line only option.
/SaveTextData[=<txtname.txt>]
Instruments and runs a program and saves the data to an expanded ASCII text file (.txt) without source code, without displaying any Purify windows. For example:
purify /SaveTextData=myapp1.txt myapp.exe
If you do not specify a file name, Purify uses <exename>.txt and saves the file in the same location as your program.
If an identically named file already exists, Purify automatically overwrites the file. You can modify this behavior by adding a filename format specifier: see Specifying unique filenames when saving files
§ Command line only option.
/ShowInstrumentationProgress=no|yes
Specifies whether to display the Instrumenting dialog box, showing Purify's progress as it instruments the executable and module files. For example:
purify /ShowInstrumentationProgress=no myapp.exe
By default, Purify shows the dialog box.
§ Command line only option.
/ShowLoadLibraryProgress=no|yes
Specifies whether to display the Instrumenting dialog box when Purify instruments files required by calls to LoadLibrary. For example:
purify /ShowLoadLibraryProgress=no myapp.exe
By default, Purify shows the dialog box.
§ Command line only option.
/SourcePath=<search path>
Specifies the search path to use to locate source files to display in your default editor or in the Purify viewer window. You can specify multiple paths by separating them with semicolons. For example:
purify /SourcePath="D:\app\src;C:\thirdpartylibs\db\src" myapp.exe
By default, Purify uses the following order to locate source files:
1. The directory where the .exe file is located.
2. The search path specified in the Files tab in the Settings for exename dialog box.
3. The directories specified in the Visual Studio Workspace file.
4. The search path specified in the Files tab in the Default Settings dialog box.
5. The MFC and Visual C++ directories.
6. The Path environment variable.
/UndoModuleList=<module1;module2;...>
Specifies previously instrumented modules that you want to restore to their original, uninstrumented state. Separate multiple modules with semicolons.
Use this option together with /UndoReplace to restore specific modules that you instrumented using the /Replace option. For example:
Purify /UndoReplace /UndoModuleList=my_other.dll;myapp.dll
Purify restores the original, uninstrumented versions of my_other.dll and myapp.dll.
§ Command line only option.
/UndoReplace
Restores all modules that you instrumented using the /Replace option to their original, uninstrumented state. For example:
Purify /UndoReplace
You can use this option together with the /UndoModuleList option to restore specific modules.
§ Command line only option.
/Usage
Displays the syntax for command-line options.
§ Command line only option.
/Version
Displays version information about the current Purify installation.
§ Command line only option.
/?
Displays the syntax for command-line options.
§ Command line only option.
filename.pfy, filename.pcy, filename.cfy
Displays a previously saved Purify error data file (.pfy), Purify error and coverage data file (.pcy), or PureCoverage data file (.cfy). You must enter the option for each file you want to open. For example:
purify myapp.pfy
Syntax Notes:
n Any Purify options you specify must precede the name of your program. Purify interprets anything after the name of your program as an argument passed to the program.
n You must place quotation marks around strings with embedded spaces. For example: /CacheDir="C:\Program Files\My Purify Tests\Cache"
n You must precede option names with a slash (/) or hyphen (-), and use an equal sign (=) to specify an option value.
n Command-line options in the online Help are always shown in mixed case. However, Purify ignores the case and any hyphens or underscores in the option name. For example, the option /leaks-at-exit is equivalent to /LEAKS_AT_EXIT and /LeaksAtExit.
(C) Copyright IBM Corporation 1992, 2010.