DynamoRIO API
dr_config.h File Reference

Deployment API for DynamoRIO. Use these functions to register processes to run under DynamoRIO, unregister processes, obtain existing registration information, and nudge running processes. More...

Macros

#define DR_MAX_OPTIONS_LENGTH   2048
 

Enumerations

enum  dr_operation_mode_t {
  DR_MODE_NONE = 0,
  DR_MODE_CODE_MANIPULATION = 1,
  DR_MODE_DO_NOT_RUN = 4
}
 
enum  dr_config_status_t {
  DR_SUCCESS,
  DR_PROC_REG_EXISTS,
  DR_PROC_REG_INVALID,
  DR_PRIORITY_INVALID,
  DR_ID_CONFLICTING,
  DR_ID_INVALID,
  DR_FAILURE,
  DR_NUDGE_PID_NOT_INJECTED,
  DR_NUDGE_TIMEOUT,
  DR_CONFIG_STRING_TOO_LONG,
  DR_CONFIG_FILE_WRITE_FAILED,
  DR_NUDGE_PID_NOT_FOUND,
  DR_CONFIG_OPTIONS_INVALID,
  DR_CONFIG_DIR_NOT_FOUND
}
 
enum  dr_platform_t {
  DR_PLATFORM_DEFAULT,
  DR_PLATFORM_32BIT,
  DR_PLATFORM_64BIT,
  DR_PLATFORM_NONE
}
 

Functions

static const char * dr_config_status_code_to_string (dr_config_status_t code)
 
DR_EXPORT dr_config_status_t dr_register_process (const char *process_name, process_id_t pid, bool global, const char *dr_root_dir, dr_operation_mode_t dr_mode, bool debug, dr_platform_t dr_platform, const char *dr_options)
 
DR_EXPORT dr_config_status_t dr_unregister_process (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)
 
DR_EXPORT dr_config_status_t dr_register_syswide (dr_platform_t dr_platform, const char *dr_root_dir)
 
DR_EXPORT dr_config_status_t dr_unregister_syswide (dr_platform_t dr_platform, const char *dr_root_dir)
 
DR_EXPORT bool dr_syswide_is_on (dr_platform_t dr_platform, const char *dr_root_dir)
 
DR_EXPORT bool dr_process_is_registered (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform, char *dr_root_dir, dr_operation_mode_t *dr_mode, bool *debug, char *dr_options)
 
DR_EXPORT dr_registered_process_iterator_t * dr_registered_process_iterator_start (dr_platform_t dr_platform, bool global)
 
DR_EXPORT bool dr_registered_process_iterator_hasnext (dr_registered_process_iterator_t *iter)
 
DR_EXPORT bool dr_registered_process_iterator_next (dr_registered_process_iterator_t *iter, char *process_name, char *dr_root_dir, dr_operation_mode_t *dr_mode, bool *debug, char *dr_options)
 
DR_EXPORT void dr_registered_process_iterator_stop (dr_registered_process_iterator_t *iter)
 
DR_EXPORT dr_config_status_t dr_register_client (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform, client_id_t client_id, size_t client_pri, const char *client_path, const char *client_options)
 
DR_EXPORT dr_config_status_t dr_unregister_client (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform, client_id_t client_id)
 
DR_EXPORT size_t dr_num_registered_clients (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)
 
DR_EXPORT dr_config_status_t dr_get_client_info (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform, client_id_t client_id, size_t *client_pri, char *client_path, char *client_options)
 
DR_EXPORT dr_client_iterator_t * dr_client_iterator_start (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)
 
DR_EXPORT bool dr_client_iterator_hasnext (dr_client_iterator_t *iter)
 
DR_EXPORT void dr_client_iterator_next (dr_client_iterator_t *iter, client_id_t *client_id, size_t *client_pri, char *client_path, char *client_options)
 
DR_EXPORT void dr_client_iterator_stop (dr_client_iterator_t *iter)
 
DR_EXPORT dr_config_status_t dr_nudge_process (const char *process_name, client_id_t client_id, uint64 arg, uint timeout_ms, int *nudge_count)
 
DR_EXPORT dr_config_status_t dr_nudge_pid (process_id_t process_id, client_id_t client_id, uint64 arg, uint timeout_ms)
 
DR_EXPORT dr_config_status_t dr_nudge_all (client_id_t client_id, uint64 arg, uint timeout_ms, int *nudge_count)
 
DR_EXPORT dr_config_status_t dr_get_config_dir (bool global, bool alternative_local, char *config_dir, size_t config_dir_sz)
 

Detailed Description

Deployment API for DynamoRIO. Use these functions to register processes to run under DynamoRIO, unregister processes, obtain existing registration information, and nudge running processes.

Note
The dr_config library is currently not multi-thread safe. Users of the library should ensure that no more then one thread accesses the library at a time. This limitation will be addressed in future releases.

Macro Definition Documentation

#define DR_MAX_OPTIONS_LENGTH   2048

Maximum length of a registered process's options string

Enumeration Type Documentation

Return status codes for process registration, unregistration and nudging.

Enumerator
DR_SUCCESS 

Operation succeeded.

DR_PROC_REG_EXISTS 

Process registration failed due to an existing registration.

DR_PROC_REG_INVALID 

Operation failed because the supplied process is not registered.

DR_PRIORITY_INVALID 

Client registration failed due to an invalid priority value.

DR_ID_CONFLICTING 

Client registration failed due to a conflicting ID.

DR_ID_INVALID 

Client operation failed due to an invalid client ID.

DR_FAILURE 

Unknown failure. Check that caller has adequate permissions for this operation.

DR_NUDGE_PID_NOT_INJECTED 

Nudge operation failed because the specified process id is not under DR.

DR_NUDGE_TIMEOUT 

Nudge operation timed out waiting for target process to finish handling a nudge.

DR_CONFIG_STRING_TOO_LONG 

Field length exceeded, probably due to a too-long option string

DR_CONFIG_FILE_WRITE_FAILED 

Failed to write to the config file.

DR_NUDGE_PID_NOT_FOUND 

Nudge operation failed because the specified process id does not exist.

DR_CONFIG_OPTIONS_INVALID 

Client options contain invalid characters (';' or all 3 quotes).

DR_CONFIG_DIR_NOT_FOUND 

Failed to locate a valid config dir. Consider calling dr_get_config_dir(, true, ,).

Specifies DynamoRIO's operation mode.

Enumerator
DR_MODE_NONE 

No mode. Clients should not attempt to register a process in this mode.

DR_MODE_CODE_MANIPULATION 

Run DynamoRIO in Code Manipulation mode.

DR_MODE_DO_NOT_RUN 

Do not run this application under DynamoRIO control. Useful for following all child processes except a handful (blacklist).

Allow targeting both 32-bit and native 64-bit processes separately.

Enumerator
DR_PLATFORM_DEFAULT 

The platform this tool is compiled for.

DR_PLATFORM_32BIT 

32-bit settings (for 32-bit processes).

DR_PLATFORM_64BIT 

64-bit settings (for native 64-bit processes).

DR_PLATFORM_NONE 

Invalid platform.

Function Documentation

DR_EXPORT bool dr_client_iterator_hasnext ( dr_client_iterator_t *  iter)
Parameters
[in]iterA client iterator created with dr_client_iterator_start()
Returns
true if there are more clients to iterate over
DR_EXPORT void dr_client_iterator_next ( dr_client_iterator_t *  iter,
client_id_t client_id,
size_t *  client_pri,
char *  client_path,
char *  client_options 
)

Return information about a client.

Parameters
[in]iterA client iterator created with dr_client_iterator_start()
[out]client_idThe unique client ID provided at client registration.
[out]client_priThe client's priority.
[out]client_pathThe client's path provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length MAX_PATH.
[out]client_optionsThe client options provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length DR_MAX_OPTIONS_LENGTH.
DR_EXPORT dr_client_iterator_t* dr_client_iterator_start ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform 
)

Creates and starts an iterator for iterating over all clients registered for the given process.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the one-time configuration for that pid will be queried. If pid == 0, the general configuration for process_name will be queried.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
Returns
iterator for use with dr_client_iterator_hasnext() and dr_client_iterator_next(). Must be freed with dr_client_iterator_stop()
DR_EXPORT void dr_client_iterator_stop ( dr_client_iterator_t *  iter)

Stops and frees a client iterator.

Parameters
[in]iterA client iterator created with dr_client_iterator_start()
static const char* dr_config_status_code_to_string ( dr_config_status_t  code)
inlinestatic

Translates dr_config_status_t code to its corresponding message string.

Parameters
[in]codedr_config_status_t code to be translated.
Returns
The translated message string.
DR_EXPORT dr_config_status_t dr_get_client_info ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform,
client_id_t  client_id,
size_t *  client_pri,
char *  client_path,
char *  client_options 
)

Retrieve client registration information for a particular process for the current user.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the one-time configuration for that pid will be queried. If pid == 0, the general configuration for process_name will be queried.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
[in]client_idThe unique client ID provided at client registration.
[out]client_priThe client's priority.
[out]client_pathThe client's path provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length MAX_PATH.
[out]client_optionsThe client options provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length DR_MAX_OPTIONS_LENGTH.
Returns
A dr_config_status_t code indicating the result of the call.
DR_EXPORT dr_config_status_t dr_get_config_dir ( bool  global,
bool  alternative_local,
char *  config_dir,
size_t  config_dir_sz 
)

Returns in config_dir the configuration directory used to store config files. In order to use local config files when the normal interactive user home directory environment variable (HOME on Linux or MacOS; USERPROFILE on Windows) is not set and when using one-step configure-and-run, call this routine prior to creating the child process and pass true for alternative_local. For multi-step, the caller must set the DYNAMORIO_CONFIGDIR environment variable (in the child process) to point at the resulting config_dir.

Parameters
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]alternative_localWhether to locate a temporary directory to use for user-local config files and to set the DYNAMORIO_CONFIGDIR environment variable to point at it, if the regular local config dir is not found.
[out]config_dirReceives the full path to the config dir.
[in]config_dir_szThe capacity, in characters, of config_dir.
Returns
A dr_config_status_t code indicating the result of the request.
DR_EXPORT dr_config_status_t dr_nudge_all ( client_id_t  client_id,
uint64  arg,
uint  timeout_ms,
int *  nudge_count 
)

Provides a mechanism for an external entity on the guest OS to communicate with a client. Requires administrative privileges. A process 'nudge' causes a client event handler to be invoked (use dr_register_nudge_event() to register the handler function). A nudge is ignored if the process is not running under DynamoRIO, the specified client is not loaded, or if the client does not provide a handler. Nudges are attempted to all processes running on the system.

Parameters
[in]client_idThe unique client ID provided at client registration.
[in]argAn argument passed to the client's nudge handler.
[in]timeout_msThe number of milliseconds to wait for each nudge to complete before continuing. If INFINITE is supplied then the wait is unbounded. If 0 is supplied the no wait is performed. If a wait times out DR_NUDGE_TIMEOUT will be returned.
[out]nudge_countReturns the number of processes nudged. Client can supply NULL if this value is not needed.
Returns
A dr_config_status_t code indicating the result of the nudge.
Remarks
A process nudge is a one way asynchronous communication from an external entity to a client. It does not allow a client to return information back to the nudge originator. To communicate from a client to another process, use the channels specified in Communication.
Note
Not yet available on Linux or MacOS.
DR_EXPORT dr_config_status_t dr_nudge_pid ( process_id_t  process_id,
client_id_t  client_id,
uint64  arg,
uint  timeout_ms 
)

Provides a mechanism for an external entity on the guest OS to communicate with a client. Requires administrative privileges. A process 'nudge' causes a client event handler to be invoked (use dr_register_nudge_event() to register the handler function). A nudge is ignored if the process is not running under DynamoRIO, the specified client is not loaded, or if the client does not provide a handler.

Parameters
[in]process_idThe system id of the process to nudge (see dr_get_process_id())
[in]client_idThe unique client ID provided at client registration.
[in]argAn argument passed to the client's nudge handler.
[in]timeout_msThe number of milliseconds to wait for the nudge to complete before returning. If INFINITE is supplied then the wait is unbounded. If 0 is supplied the no wait is performed. If the wait times out DR_NUDGE_TIMEOUT will be returned.
Returns
A dr_config_status_t code indicating the result of the nudge.
Remarks
A process nudge is a one way asynchronous communication from an external entity to a client. It does not allow a client to return information back to the nudge originator. To communicate from a client to another process, use the channels specified in Communication.
Note
Not yet available on MacOS.
DR_EXPORT dr_config_status_t dr_nudge_process ( const char *  process_name,
client_id_t  client_id,
uint64  arg,
uint  timeout_ms,
int *  nudge_count 
)

Provides a mechanism for an external entity on the guest OS to communicate with a client. Requires administrative privileges. A process 'nudge' causes a client event handler to be invoked (use dr_register_nudge_event() to register the handler function). A nudge is ignored if the process is not running under DynamoRIO, the specified client is not loaded, or if the client does not provide a handler.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable.
[in]client_idThe unique client ID provided at client registration.
[in]argAn argument passed to the client's nudge handler.
[in]timeout_msThe number of milliseconds to wait for each nudge to complete before continuing. If INFINITE is supplied then the wait is unbounded. If 0 is supplied the no wait is performed. If a wait times out DR_NUDGE_TIMEOUT will be returned.
[out]nudge_countReturns the number of processes nudged. Client can supply NULL if this value is not needed.
Returns
A dr_config_status_t code indicating the result of the nudge.
Remarks
If there are multiple processes executing with the same name, all of them are nudged.
A process nudge is a one way asynchronous communication from an external entity to a client. It does not allow a client to return information back to the nudge originator. To communicate from a client to another process, use the channels specified in Communication.
Note
Not yet available on Linux or MacOS.
DR_EXPORT size_t dr_num_registered_clients ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform 
)

Retrieve the number of clients registered for a particular process for the current user.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the one-time configuration for that pid will be queried. If pid == 0, the general configuration for process_name will be queried.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
Returns
The number of clients registered for the given process and platform.
DR_EXPORT bool dr_process_is_registered ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform,
char *  dr_root_dir,
dr_operation_mode_t dr_mode,
bool *  debug,
char *  dr_options 
)

Check if a process is registered to run under DynamoRIO. To obtain client information, use dr_get_client_info().

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the one-time configuration for that pid will be queried. If pid == 0, the general configuration for process_name will be queried.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
[out]dr_root_dirIf the process is registered, the root DynamoRIO directory provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length MAX_PATH.
[out]dr_modeIf the process is registered, the mode provided at registration. Callers can pass NULL if this value is not needed.
[out]debugIf the process is registered, the debug flag provided at registration. Callers can pass NULL if this value is not needed.
[out]dr_optionsIf the process is registered, the extra DynamoRIO parameters provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length DR_MAX_OPTIONS_LENGTH.
Returns
true if the process is registered for the given platform.
DR_EXPORT dr_config_status_t dr_register_client ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform,
client_id_t  client_id,
size_t  client_pri,
const char *  client_path,
const char *  client_options 
)

Register a client for a particular process. Note that the process must first be registered via dr_register_process() before calling this routine.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the one-time configuration for that pid will be modified. If pid == 0, the general configuration for process_name will be modified.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
[in]client_idA client_id_t uniquely identifying the client. DynamoRIO provides the client ID as a parameter to dr_client_main(). Clients use this ID to retrieve client-specific path and option information. Outside entities also identify the target of a nudge via this ID.
[in]client_priThe client number, or priority. Client registration includes a value indicating the priority of a client relative to other clients. In multi-client settings, a client's priority influences event callback ordering. That is, higher priority clients can register their callbacks first; DynamoRIO then calls these routines last. Client priorities range consecutively from 0 to N-1, where N is the number of registered clients. Specify priority 0 to register a client with highest priority.
[in]client_pathA NULL-terminated string specifying the full path to a valid client library. The string length cannot exceed MAX_PATH. The client path may not include any semicolons and when combined with client_options may not include all three quote characters (', ", `) simultaneously.
[in]client_optionsA NULL-terminated string specifying options that are available to the client as arguments of dr_client_main() or via dr_get_option_array(). The string length cannot exceed DR_MAX_OPTIONS_LENGTH. The client options may not include any semicolons and when combined with client_path may not include all three quote characters (', ", `) simultaneously.
Returns
A dr_config_status_t code indicating the result of registration.
DR_EXPORT dr_config_status_t dr_register_process ( const char *  process_name,
process_id_t  pid,
bool  global,
const char *  dr_root_dir,
dr_operation_mode_t  dr_mode,
bool  debug,
dr_platform_t  dr_platform,
const char *  dr_options 
)

Register a process to run under DynamoRIO. Note that this routine only sets the base options to run a process under DynamoRIO. To register one or more clients, call dr_register_client() subsequently.

In order to use local config files when the normal interactive user home directory environment variable (HOME on Linux or MacOS; USERPROFILE on Windows) is not set and when using one-step configure-and-run (i.e., when pid != 0), call dr_get_config_dir() prior to creating the child process (and prior to calling this routine) and pass true for alternative_local. For multi-step, the caller must set the DYNAMORIO_CONFIGDIR environment variable before calling this routine.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, a one-time configuration is created just for it. If pid == 0, a general configuration is created for all future instances of process_name.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_root_dirA NULL-terminated string specifying the full path to a valid DynamoRIO root directory. The string length cannot exceed MAX_PATH.
[in]dr_modeSpecifies the mode under which DynamoRIO should operate. See dr_operation_mode_t.
[in]debugIf true, a DynamoRIO debug build will be used; otherwise, a release build will be used.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to set.
[in]dr_optionsA NULL-terminated string controlling DynamoRIO's behavior. Most users should not need to specify options. The total string length cannot exceed DR_MAX_OPTIONS_LENGTH.
Returns
A dr_config_status_t code indicating the result of registration. Note that registration fails if the requested process is already registered. To modify a process's registration, first call dr_unregister_process() to remove an existing registration.
Remarks
After registration, a process will run under DynamoRIO when launched by the drinject tool or using drinjectlib. Note that some processes may require a system reboot to restart. Process registration that is not specific to one pid (i.e., if pid == 0) persists across reboots until explicitly unregistered.
DR_EXPORT dr_config_status_t dr_register_syswide ( dr_platform_t  dr_platform,
const char *  dr_root_dir 
)

Sets up systemwide injection so that registered applications will run under DynamoRIO however they are launched (i.e., they do not need to be explicitly invoked with the drrun or drinject tools). This requires administrative privileges and affects all users (though configurations remain private to each user). On Windows NT, a reboot is required for this to take effect.

Parameters
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those to use.
[in]dr_root_dirThe root DynamoRIO directory.
Returns
A dr_config_status_t code indicating the result of the operation. The operation will fail if the caller does not have sufficient privileges.
Note
On Windows, an application that does not link with user32.dll will not be run under control of DynamoRIO via systemwide injection. Such applications will only be under DynamoRIO control if launched by the drrun or drinject tools or if the parent process (typically explorer.exe, for manually launched applications) is already under DynamoRIO control (the parent can be in any mode, but a 32-bit parent cannot inject into a 64-bit child). Only some small non-graphical applications do not link with user32.dll.
Not yet available on Linux or MacOS.
DR_EXPORT bool dr_registered_process_iterator_hasnext ( dr_registered_process_iterator_t *  iter)
Parameters
[in]iterA registered process iterator created with dr_registered_process_iterator_start()
Returns
true if there are more registered processes to iterate over
Note
Not yet available on Linux or MacOS.
DR_EXPORT bool dr_registered_process_iterator_next ( dr_registered_process_iterator_t *  iter,
char *  process_name,
char *  dr_root_dir,
dr_operation_mode_t dr_mode,
bool *  debug,
char *  dr_options 
)

Return information about a registered process

Parameters
[in]iterA registered process iterator created with dr_registered_process_iterator_start().
[out]process_nameThe name of the registered process. Callers can pass NULL if this value is not needed. Otherwise the parameter must be a caller-allocated array of length MAX_PATH.
[out]dr_root_dirThe root DynamoRIO directory provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length MAX_PATH.
[out]dr_modeIf the process is registered, the mode provided at registration. Callers can pass NULL if this value is not needed.
[out]debugIf the process is registered, the debug flag provided at registration. Callers can pass NULL if this value is not needed.
[out]dr_optionsIf the process is registered, the extra DynamoRIO parameters provided at registration. Callers can pass NULL if this value is not needed. Otherwise, the parameter must be a caller-allocated array of length DR_MAX_OPTIONS_LENGTH.
Returns
true if the information was successfully retrieved.
Note
Not yet available on Linux or MacOS.
DR_EXPORT dr_registered_process_iterator_t* dr_registered_process_iterator_start ( dr_platform_t  dr_platform,
bool  global 
)

Creates and starts an iterator for iterating over all processes registered for the given platform and given global or local parameter.

Parameters
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
Returns
iterator for use with dr_registered_process_iterator_hasnext()and dr_registered_process_iterator_next(). Must be freed with dr_registered_process_iterator_stop()
Note
Not yet available on Linux or MacOS.
DR_EXPORT void dr_registered_process_iterator_stop ( dr_registered_process_iterator_t *  iter)

Stops and frees a registered process iterator.

Parameters
[in]iterA registered process iterator created with dr_registered_process_iterator_start()
Note
Not yet available on Linux or MacOS.
DR_EXPORT bool dr_syswide_is_on ( dr_platform_t  dr_platform,
const char *  dr_root_dir 
)

Returns whether systemwide injection is enabled.

Parameters
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those to use.
[in]dr_root_dirThe root DynamoRIO directory.
Returns
Whether systemwide injection is enabled.
Note
Not yet available on Linux or MacOS.
DR_EXPORT dr_config_status_t dr_unregister_client ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform,
client_id_t  client_id 
)

Unregister a client for a particular process.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the one-time configuration for that pid will be modified. If pid == 0, the general configuration for process_name will be modified.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
[in]client_idThe unique client ID provided at client registration.
Returns
A dr_config_status_t code indicating the result of unregistration.
DR_EXPORT dr_config_status_t dr_unregister_process ( const char *  process_name,
process_id_t  pid,
bool  global,
dr_platform_t  dr_platform 
)

Unregister a process from running under DynamoRIO.

Parameters
[in]process_nameA NULL-terminated string specifying the name of the target process. The string should identify the base name of the process, not the full path of the executable (e.g., calc.exe).
[in]pidA process id of a target process, typically just created and suspended via dr_inject_process_exit(). If pid != 0, the existing one-time configuration is removed. If pid == 0, the general configuration for process_name is removed.
[in]globalWhether to use global or user-local config files. On Windows, global config files are stored in a dir pointed at by the DYNAMORIO_HOME registry key. On Linux, they are in /etc/dynamorio. Administrative privileges may be needed if global is true. Note that DynamoRIO gives local config files precedence when both exist. The caller must separately create the global directory.
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to set.
Returns
A dr_config_status_t code indicating the result of unregistration. Note that unregistration fails if the process is not currently registered to run under DynamoRIO.
DR_EXPORT dr_config_status_t dr_unregister_syswide ( dr_platform_t  dr_platform,
const char *  dr_root_dir 
)

Disables systemwide injection. Registered applications will not run under DynamoRIO unless explicitly launched with the drrun or drinject tools (or a custom tool that uses the drinjectlib library). On Windows NT, a reboot is required for this to take effect.

Parameters
[in]dr_platformConfigurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those to use.
[in]dr_root_dirThe root DynamoRIO directory.
Returns
A dr_config_status_t code indicating the result of the operation. The operation will fail if the caller does not have sufficient privileges.
Note
Not yet available on Linux or MacOS.