DynamoRIO
DynamoRIO Option Parser

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

Setup

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.

Usage

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"
int
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.

Aliases

To support multiple strings to trigger the same option, pass a vector of strings as the name, with the primary name (the one used in usage reports) listed first, like this:

// We support the legacy name as an alias for compatibility.
// We explicitly specity the vector type to avoid ambiguity with iterators
// when we have just 2 elements in the list.
DROPTION_SCOPE_CLIENT, std::vector<std::string>({ "blocklist", "blacklist" }),
IF_WINDOWS_ELSE("ntdll.dll", ""), ":-separated list of libs to ignore.",
"The blocklist is a :-separated list of library names for which violations "
"should not be reported.");

Clearing Accumulated Values on Re-attach

For options that accumulate values (DROPTION_FLAG_ACCUMULATE), a re-attach with a statically linked client will keep the old value from the prior attach. The droption_parser_t::clear_values() function can be called from the client on exit or initialization to clear all the values.

DR_API void dr_abort(void)
Options parsing support.
@ DROPTION_SCOPE_ALL
Definition: droption.h:75
Definition: droption.h:403
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:313
#define STDERR
Definition: dr_defines.h:342
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:967
@ DROPTION_SCOPE_CLIENT
Definition: droption.h:72
static bool parse_argv(unsigned int scope, int argc, const char *argv[], std::string *error_msg, int *last_index)
Definition: droption.h:194