Once you have installed Dr. Memory and built your application properly, the next step is to execute it on your workload of choice under Dr. memory.
To fuzz test an application, use Dr. Memory's Fuzz Testing Mode.
Dr. Memory has support for running within the Visual Studio IDE as an External Tool. The Windows installer automatically creates a new Tools menu entry for launching Dr. Memory for each version of Visual Studio detected at install time. If you are using a local install, or if you installed Visual Studio after installing Dr. Memory, or if you are using Visual Studio Express 2010 and it was in Basic mode at the time you installed Dr. Memory, you will need to follow the following instructions in order to add Dr. Memory as an External Tool.
If using Visual Studio Express 2010, first enable the full menu system by selecting Tools | Settings | Expert Settings
(this step is not necessary for Visual Studio Professional or later versions of Visual Studio Express).
Next, for Visual Studio 2005 through 2012, select the Tools | External Tools...
menu option to open the External Tools dialog box. Click Add and fill in the fields as follows (adjusting the path to drmemory.exe
if you installed it somewhere else):
Title: Dr. Memory Command: C:\Program Files (x86)\Dr. Memory\bin\drmemory.exe Arguments: -visual_studio -- $(TargetPath) Initial Directory: $(TargetDir)
Check the Use Output window
checkbox. Click OK.
For Visual Studio 6, select Tools | Customize
, then the Tools
tab, and then click the New
button. Fill in the fields as above, though the Title
field is instead the input box in the main list. Also, you'll want quotes around the TargetPath variable (but you do not want quotes for any later Visual Studio version):
Command: C:\Program Files\Dr. Memory\bin\drmemory.exe Arguments: -visual_studio -- "$(TargetPath)" Initial Directory: $(TargetDir)
Now you can select Tools | Dr. Memory
and Visual Studio will run your application. The output of Dr. Memory (along with your program) will be printed to the Output Window. You can double-click on a source file on any callstack frame in order to automatically open up that file to the line number indicated.
To pass arguments to your application, in the External Tools dialog box entry for Dr. Memory, either directly add them for all runs, or check the "Prompt for arguments" checkbox to be prompted for arguments on each invocation. Add application arguments at the end, after the pre-filled-in string:
-visual_studio -- $(TargetPath) ADD ARGUMENTS HERE
.
For Dr. Memory as an External Tool set up by the Dr. Memory installer, prompting for arguments is on by default.
Run your application as you normally would from a command prompt (on Windows, either the cmd
shell or a Cygwin prompt), with drmemory
and "--" prefixed to the command line (the "--" separates any arguments to Dr. Memory from the application being run).
On Windows:
drmemory.exe -- c:/path/to/my/app args to my app
On Linux or Mac:
drmemory -- /path/to/my/app args to my app
Examples throughout the rest of the documentation will use just one platform, but can readily be adapted to the other by changing the front-end (drmemory.exe
or drmemory
) and the path style.
If as part of Installing Dr. Memory you did not add Dr. Memory to your path, you'll need to specify the full path to Dr. Memory.
On Windows, you can also drag-and-drop your application onto drmemory.exe
in Windows Explorer or on the Desktop if you requested a Desktop shorcut upon installation.
When running scripts it is best to explicitly invoke the interpreter rather than invoking the script directly. For example:
drmemory -- /usr/bin/perl ./myscript.pl
Dr. Memory's results are written to a file called results.txt
inside a subdirectory created for each invocation of Dr. Memory, inside Dr. Memory's log directory. The log directory by default is the logs
subdirectory of the unpacked installation, or the Dr. Memory directory inside your profile directory when Dr. Memory is installed into Program Files
on Windows. It can be changed with the -logdir
option:
drmemory.exe -logdir c:/logs -- c:/path/to/my/app
When an application is executed under Dr. Memory's control, it creates a subdirectory in the base log directory named "DrMemory-<appname>.<pid>.NNN", where NNN is a counter that is incremented to ensure unique names.
On Windows, the results files is automatically opened in notepad
when the application exits. This only occurs for the top-level process; if it created child processes, they will be followed by Dr. Memory and have their own result directories and files, but these will not be automatically displayed. The option -batch
can be used to disable the launch of notepad
at application exit.
For full details on each type of error reported by Dr. Memory, see Error Types Reported by Dr. Memory.
If you would like to attach a debugger at the point an error is first detected, use the -pause_at_unaddressable
or -pause_at_uninitialized
options (see Dr. Memory Runtime Option Reference).
Current versions of Dr. Memory can end up reporting uninitialized read and leak errors in system library code on large Windows applications. Future Dr. Memory versions will eliminate these errors, but for now these likely false positive errors are listed in a separate file from the normal results.txt
called potential_errors.txt
. The count of such errors is listed in the ERRORS IGNORED
section of the main error summary. For example:
ERRORS IGNORED: 17 potential error(s) (suspected false positives) (details: D:\drmemory\logs\DrMemory-myapp.exe.5144.000\potential_errors.txt) 24 potential leak(s) (suspected false positives) (details: D:\drmemory\logs\DrMemory-myapp.exe.5144.000\potential_errors.txt)
It is possible that some of these errors are in fact application errors in parameters passed to system library routines where those parameters are not used or read until deep into a system library callstack, though they are suspected of being false positives due to being reported in several layers of system library code. The pattern checking used to identify system libraries whose errors should be reported separately can be tuned via two features, a blacklist and a whitelist. Each feature contains patterns against which file paths are matched. These patterns can contain *
or ? wildcards.
The whitelist takes precedence and if set the blacklist is ignored. The whitelist is empty by default. The option -lib_whitelist
contains a ;-separated sequence of patterns against which library or executable paths are matched. The option -lib_whitelist_frames
controls how many of the top frames in each callstack are matched. If a whitelist pattern appears in any of those top frames, an error is reported normally. Otherwise, it is separated as a potential error. The expected usage model is to populate the whitelist with a list of paths in which application libraries or executables reside, to limit the error reports to those paths.
The blacklist is controlled by parallel options -lib_blacklist
and -lib_blacklist_frames
. Running with -lib_blacklist_frames 0
will disable the blacklist and report all errors as application errors in results.txt
. When non-zero, it controls how many of the top frames must all match the blacklist before an error is separated as a potential error. The blacklist is only enabled by default on Windows, where it is set to $SYSTEMROOT*
.d??.
An additional whitelist based on source file paths is available under the options -src_whitelist
and -src_whitelist_frames
. If combined with -lib_whitelist
, the library-based whitelist acts first, with the source file-based whitelist filtering the errors that remain.
If many false positives are being reported and additional performance is desired at the risk of not detecting all application errors, Dr. Memory's Light Mode can be used to disable checking for uninitialized reads and leaks.
Dr. Memory has an additional type of blacklist beyond the blacklist for system library errors described in Application Versus System Library Errors. This blacklist is controlled by the option -check_uninit_blacklist
, which is a ,-separated list of library names. Unlike the other blacklist, these names are basenames and not whole paths, as they are meant to correspond to library names given in suppression files. For each library on this list, Dr. Memory will not report any uninitialized reads while directly executing the library's code. This is a more efficient means to eliminate errors than using suppressions or the -lib_blacklist
option, but it only applies to uninitialized reads.
When Dr. Memory sees a whole-module suppression – a suppression containing only a single frame of the form "name!*" – it automatically adds "name" to the -check_uninit_blacklist
option list.
By default, Dr. Memory monitors all child processes. To disable this behavior and not monitor any children, use this option:
drmemory.exe -no_follow_children -- c:/path/to/my/app
On Windows, to follow all children except certain applications, run this command with the executable name of each application you do not wish to monitor, prior to running Dr. Memory with default options:
drconfig.exe -quiet -reg <myapp> -norun
Where "myapp" is the basename of your executable (i.e., the file name without any directories).
The drconfig.exe
tool is in the same directory as drmemory.exe
and is only available on Windows in the current release.
This -norun
request is permanent and affects all subsequent Dr. Memory executions by the user that issued the -norun
request. To undo it, use this command:
drconfig.exe -quiet -unreg <myapp>
While Dr. Memory updates the results.txt
file as the application runs, it does not perform leak checking or produce a summary of errors until the end of the run. For applications that do not have a normal exit, such as daemons, Dr. Memory provides a method of forcing end-of-run actions.
Run drmemory
with the -nudge
option and the process identifier of the application in order to request leak checking and other end-of-run actions:
drmemory.exe -nudge <processid>
Dr. Memory's default options are set up to find the most errors. Several key options can be adjusted to improve performance, at the cost of less information on each error report or even identification of fewer error types. Reducing -malloc_max_frames
, disabling -delay_frees_stack
, and disabling leak checking can improve performance on malloc-intensive applications. For more significant improvements, consider using Dr. Memory's Light Mode.