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 as a Visual Studio Tool

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.

Invoking Dr. Memory from the Command Line

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, 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.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.

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

Examining the Results

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). 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

Application Versus System Library Errors

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 blocklist and an allowlist. Each feature contains patterns against which file paths are matched. These patterns can contain * or ? wildcards.

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 and -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 and -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.

Eliminating Uninitialized Read Checks By Library

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.

Controlling Child Processes

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>

Applications That Do Not Exit

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>

Tuning for Performance

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.