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)
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).
drmemory.exe -- c:/path/to/my/app args to my app
On Linux, Mac, or an Android native application:
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) 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.
For Java applications on Android, see the information under Preparing Your Application for Android.
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
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_uninitialized options (see Dr. Memory Runtime Option Reference). Unfortunately, full debugger integration is not yet implemented, and the current PC and top few callstack frames are inside the Dr. Memory tool when attaching at the pause point. When using the Debugging Tools for Windows debugger, switching to a pure application context can be done using a script provided by DynamoRIO for 64-bit or for 32-bit to load the tool symbols. Once loaded, use the CONTEXT local variable provided by Dr. Memory in the drmemorylib!report_pause_at_error frame to swap to the application context via the debugger command ".cxr". This would look something like this from the windbg prompt:
$><c:\downloaded\path\to\load_syms64 ~0s kn .frame 4 .cxr cxt kn
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
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 blocklist and an allowlist. Each feature contains patterns against which file paths are matched. These patterns can contain
The allowlist takes precedence and if set the blocklist is ignored. The allowlist is empty by default. The option
-lib_allowlist contains a ;-separated sequence of patterns against which library or executable paths are matched. The option
-lib_allowlist_frames controls how many of the frames in each callstack, starting from the top frame, are examined. If an allowlist pattern appears in any one or more 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 allowlist with a list of paths in which application libraries or executables reside, to limit the error reports to those paths.
The blocklist is controlled by parallel options
-lib_blocklist_frames. Running with
-lib_blocklist_frames 0 will disable the blocklist 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 blocklist before an error is separated as a potential error. I.e., there must be
-lib_blocklist_frames frames in a row that match a blocklist entry (unlike the allowlist where only a single frame must match).. The blocklist is only enabled by default on Windows. There is a separate option
-lib_blocklist_default which is appended to
-lib_blocklist and whose default value matches libraries in $SYSTEMROOT and in the "Microsoft Shared" directories inside $CommonProgramFiles and $CommonProgramFiles(x86). This separate option is intended to not be set by users; instead, users set the
-lib_blocklist option and so avoid affecting the default values.
An additional allowlist based on source file paths is available under the options
-src_allowlist_frames. If combined with
-lib_allowlist, the library-based allowlist acts first, with the source file-based allowlist 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 blocklist beyond the blocklist for system library errors described in Application Versus System Library Errors. This blocklist is controlled by the option
-check_uninit_blocklist, which is a ,-separated list of library names. Unlike the other blocklist, 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_blocklist 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_blocklist 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).
drconfig.exe tool is in the same directory as
drmemory.exe and is only available on Windows in the current release.
-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.
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
-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.