DynamoRIO Option Parser

The droption DynamoRIO Extension provides easy-to-use option declaration and parsing for both clients and standalone programs.


To use droption with your client simply include this line in your client's CMakeLists.txt file:

use_DynamoRIO_extension(clientname droption)

That will automatically set up the include path. Then include the header file:

#include "droption.h"

To use droption with a non-client, for example with a tool frontend or other standalone application, simply include the droption.h header file.


Simply declare a global instance of droption_t of the desired option value type for each option you wish to support. Typical value types are bool, integers, or std::string. For example:

(DROPTION_SCOPE_CLIENT, "x", 0, 0, 64, "Some param",
"Longer desc of some param.");
(DROPTION_SCOPE_CLIENT, "y", "", "Another param",
"Longer desc of another param.");
static droption_t<int> op_z
(DROPTION_SCOPE_CLIENT, "foo", 42, "Yet another param",
"Longer desc of yet another param.");

Then, ask for the droption_t instances to be filled in from the passed-in arguments from the user. In a client using dr_client_main(), or from a standalone application, invoke parse_argv():

std::string parse_err;
if (!droption_parser_t::parse_argv(DROPTION_SCOPE_CLIENT, argc, argv, &parse_err)) {
dr_fprintf(STDERR, "Usage error: %s", parse_err.c_str());

A standalone application should pass DROPTION_SCOPE_FRONTEND rather than DROPTION_SCOPE_CLIENT.

In a client using the legacy dr_init(), use the dr_parse_options() function:

std::string parse_err;
if (!dr_parse_options(id, &parse_err)) {
dr_fprintf(STDERR, "Usage error: %s", parse_err.c_str());

A boolean option foo can be negated on the command line using any of the following prefixes:

  • -nofoo
  • -no_foo
  • –nofoo
  • –no_foo

Option values are retrieved with get_value:

if (op_x.get_value() > 4) {

The value set on the command line can be overridden with the set_value function.

Supported Types

droption only supports the following standard value types for options:

  • int
  • long
  • long long
  • unsigned int
  • unsigned long
  • unsigned long long
  • double
  • bool

droption also provides some custom value types for options:

  • bytesize_t: this class provides an integer type that accepts suffixes like 'K', 'M', and 'G' when specifying sizes in units of bytes.
  • twostring_t: built-in support for a pair of strings as values.

Automated HTML

To produced automated documentation with the long-format descriptions, we recommend building a small program that looks something like this:

#include <iostream>
#include "droption.h"
#include "options.h"
main(int argc, const char *argv[])
"- <b>", "</b>\n",
" <br><i>", "</i>\n",
" <br>", "\n")
<< std::endl;
return 0;

This program can be built and run at documentation generation time to produce HTML that can then be embedded into Doxygen or other documentation.

DR_API void dr_abort(void)
Options parsing support.
Definition: droption.h:74
Definition: droption.h:366
static std::string usage_long(unsigned int scope, std::string pre_name="----------\n", std::string post_name="\n", std::string pre_value="", std::string post_value="\n", std::string pre_desc="", std::string post_desc="\n")
Definition: droption.h:294
#define STDERR
Definition: dr_defines.h:335
DR_API ssize_t dr_fprintf(file_t f, const char *fmt,...)
static bool dr_parse_options(client_id_t client_id, std::string *error_msg, int *last_index)
Definition: droption.h:835
Definition: droption.h:71
static bool parse_argv(unsigned int scope, int argc, const char *argv[], std::string *error_msg, int *last_index)
Definition: droption.h:177