DynamoRIO Option Parser

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

• Setup
• Usage
• Supported Types
• Automated HTML
• Aliases
• Clearing Accumulated Values on Re-attach

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:

using ::dynamorio::droption::DROPTION_SCOPE_CLIENT;
using ::dynamorio::droption::droption_t;
 
static droption_t<unsigned int> op_x
(DROPTION_SCOPE_CLIENT, "x", 0, 0, 64, "Some param",
 "Longer desc of some param.");
 
static droption_t<std::string> op_y
(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():

using ::dynamorio::droption::droption_parser_t;
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());
    dr_abort();
}

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());
    dr_abort();
}

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"
 
using ::dynamorio::droption::droption_parser_t;
using ::dynamorio::droption::DROPTION_SCOPE_ALL;
 
int
main(int argc, const char *argv[])
{
    std::cout << droption_parser_t::usage_long(DROPTION_SCOPE_ALL,
                                               "- <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:

droption_t<std::string> op_blocklist(
    // 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 (dynamorio::droption::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.