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

Data Structures
struct	_dr_config_client_t

Macros
#define	DR_MAX_OPTIONS_LENGTH 2048

Typedefs
typedef struct _dr_config_client_t	dr_config_client_t

Enumerations
enum	dr_operation_mode_t { DR_MODE_NONE = 0, DR_MODE_CODE_MANIPULATION = 1, DR_MODE_PROBE = 2, DR_MODE_MEMORY_FIREWALL = 3, 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, DR_CONFIG_INVALID_PARAMETER, DR_CONFIG_CLIENT_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_inject_paths (const char process_name, process_id_t pid, bool global, dr_platform_t dr_platform, const char dr_lib_path, const char *dr_alt_lib_path)

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_register_client_ex (const char process_name, process_id_t pid, bool global, dr_platform_t dr_platform, DR_PARAM_IN dr_config_client_t client)

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_config_status_t	dr_get_client_info_ex (const char process_name, process_id_t pid, bool global, dr_platform_t dr_platform, dr_config_client_t client)

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 dr_config_status_t	dr_client_iterator_next_ex (dr_client_iterator_t iter, dr_config_client_t client)

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

◆ DR_MAX_OPTIONS_LENGTH

#define DR_MAX_OPTIONS_LENGTH 2048

Maximum length of a registered process's options string

Typedef Documentation

◆ dr_config_client_t

typedef struct _dr_config_client_t dr_config_client_t

Information about a client library setup.

Enumeration Type Documentation

◆ dr_config_status_t

enum dr_config_status_t

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, ,).
DR_CONFIG_INVALID_PARAMETER	A parameter was not set.
DR_CONFIG_CLIENT_NOT_FOUND	A primary client configuration was not found at the time an alternate bitwidth client was attempted to be registered.

◆ dr_operation_mode_t

enum dr_operation_mode_t

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. This does not preclude using the Probe API.
DR_MODE_PROBE	Run DynamoRIO in Probe mode. This mode has no code cache. Warning This mode is not fully supported at this time.
DR_MODE_MEMORY_FIREWALL	Run DynamoRIO in security Memory Firewall mode. Warning This mode is not fully supported at this time.
DR_MODE_DO_NOT_RUN	Do not run this application under DynamoRIO control. Useful for following all child processes except a handful (blocklist).

◆ dr_platform_t

enum dr_platform_t

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_client_iterator_hasnext()

DR_EXPORT bool dr_client_iterator_hasnext ( dr_client_iterator_t * iter )

Parameters

[in] iter A client iterator created with dr_client_iterator_start()

Returns: true if there are more clients to iterate over

◆ dr_client_iterator_next()

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]	iter	A client iterator created with dr_client_iterator_start()
[out]	client_id	The unique client ID provided at client registration.
[out]	client_pri	The client's priority.
[out]	client_path	The 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 MAXIMUM_PATH.
[out]	client_options	The 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_client_iterator_next_ex()

DR_EXPORT dr_config_status_t dr_client_iterator_next_ex	(	dr_client_iterator_t *	iter,
		dr_config_client_t *	client
	)

Return information about a client.

Parameters

[in]	iter	A client iterator created with dr_client_iterator_start()
[out]	client	The returned information about the client. On input, the struct_size field must be set and the client_path and client_options fields must each either be NULL if that data is not needed or point at a caller-allocated array of length MAXIMUM_PATH for client_path or DR_MAX_OPTIONS_LENGTH for client_options.

◆ dr_client_iterator_start()

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_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations 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_client_iterator_stop()

DR_EXPORT void dr_client_iterator_stop ( dr_client_iterator_t * iter )

Stops and frees a client iterator.

Parameters

[in] iter A client iterator created with dr_client_iterator_start()

◆ dr_config_status_code_to_string()

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] code dr_config_status_t code to be translated.

Returns: The translated message string.

◆ dr_get_client_info()

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. If multiple clients are registered (alternative bitwidth clients are considered separate), information on the highest-priority client is returned.

Parameters

[in]	process_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
[in]	client_id	The unique client ID provided at client registration.
[out]	client_pri	The client's priority.
[out]	client_path	The 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 MAXIMUM_PATH.
[out]	client_options	The 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_get_client_info_ex()

DR_EXPORT dr_config_status_t dr_get_client_info_ex	(	const char *	process_name,
		process_id_t	pid,
		bool	global,
		dr_platform_t	dr_platform,
		dr_config_client_t *	client
	)

Retrieve client registration information for a particular process for the current user. If multiple clients are registered (alternative bitwidth clients are considered separate), information on the highest-priority client is returned.

Parameters

[in]	process_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
[out]	client	The returned information about the client. On input, the struct_size field must be set and the client_id field set to the unique client ID provided at client registration to be queried. Furthermore, the client_path and client_options fields must each either be NULL if that data is not needed or point at a caller-allocated array of length MAXIMUM_PATH for client_path or DR_MAX_OPTIONS_LENGTH for client_options.

Returns: A dr_config_status_t code indicating the result of the call.

◆ dr_get_config_dir()

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]	global	Whether 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_local	Whether 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_dir	Receives the full path to the config dir.
[in]	config_dir_sz	The capacity, in characters, of `config_dir`.

Returns: A dr_config_status_t code indicating the result of the request.

◆ dr_nudge_all()

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_id	The unique client ID provided at client registration.
[in]	arg	An argument passed to the client's nudge handler.
[in]	timeout_ms	The 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_count	Returns 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_nudge_pid()

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_id	The system id of the process to nudge (see dr_get_process_id())
[in]	client_id	The unique client ID provided at client registration.
[in]	arg	An argument passed to the client's nudge handler.
[in]	timeout_ms	The 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_nudge_process()

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_name	A 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_id	The unique client ID provided at client registration.
[in]	arg	An argument passed to the client's nudge handler.
[in]	timeout_ms	The 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_count	Returns 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_num_registered_clients()

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_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations 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. An alternative bitwidth client is counted as a separate client.

◆ dr_process_is_registered()

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_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
[out]	dr_root_dir	If 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 MAXIMUM_PATH.
[out]	dr_mode	If the process is registered, the mode provided at registration. Callers can pass NULL if this value is not needed.
[out]	debug	If the process is registered, the debug flag provided at registration. Callers can pass NULL if this value is not needed.
[out]	dr_options	If 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_register_client()

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_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to set.
[in]	client_id	A 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_pri	The 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_path	A NULL-terminated string specifying the full path to a valid client library. The string length cannot exceed MAXIMUM_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_options	A 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_register_client_ex()

DR_EXPORT dr_config_status_t dr_register_client_ex	(	const char *	process_name,
		process_id_t	pid,
		bool	global,
		dr_platform_t	dr_platform,
		DR_PARAM_IN dr_config_client_t *	client
	)

Register a client for a particular process. Note that the process must first be registered via dr_register_process() before calling this routine. The dr_config_client_t structure allows specifying additional options beyond what dr_register_client() supports, such as an alternate bitwidth client. For an alternate bitwidth client, the main client must first be registered by an earlier call. Unregistering a client with dr_unregister_client() will also unregister the alternate bitwidth client.

Parameters

[in]	process_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to set.
[in]	client	Defines the attributes of the client to be registered.

Returns: A dr_config_status_t code indicating the result of registration.

◆ dr_register_inject_paths()

DR_EXPORT dr_config_status_t dr_register_inject_paths	(	const char *	process_name,
		process_id_t	pid,
		bool	global,
		dr_platform_t	dr_platform,
		const char *	dr_lib_path,
		const char *	dr_alt_lib_path
	)

Sets the paths to the DynamoRIO library and the alternate-bitwidth DynamoRIO library for a process that has already been registered via dr_register_process(). If this routine is not called, default library paths will be used which assume a default path layout within the dr_root_dir passed to dr_register_process().

Parameters

[in]	process_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
[in]	dr_lib_path	A NULL-terminated string specifying the full path to a valid DynamoRIO library of the same bitwidth as `dr_platform`. The string length cannot exceed MAXIMUM_PATH.
[in]	dr_alt_lib_path	A NULL-terminated string specifying the full path to a valid DynamoRIO library of the alternative bitwidth to `dr_platform`. The string length cannot exceed MAXIMUM_PATH.

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_register_process()

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_name	A 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]	pid	A 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]	global	Whether 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_dir	A NULL-terminated string specifying the full path to a valid DynamoRIO root directory. The string length cannot exceed MAXIMUM_PATH. The path to the DynamoRIO library to be used will be constructed from this path assuming a default layout. To precisely specify the path, call dr_register_inject_paths() afterward.
[in]	dr_mode	Specifies the mode under which DynamoRIO should operate. See dr_operation_mode_t.
[in]	debug	If true, a DynamoRIO debug build will be used; otherwise, a release build will be used.
[in]	dr_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to set.
[in]	dr_options	A 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_register_syswide()

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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those to use.
[in]	dr_root_dir	The 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_registered_process_iterator_hasnext()

DR_EXPORT bool dr_registered_process_iterator_hasnext ( dr_registered_process_iterator_t * iter )

Parameters

[in] iter A 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_registered_process_iterator_next()

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]	iter	A registered process iterator created with dr_registered_process_iterator_start().
[out]	process_name	The 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 MAXIMUM_PATH.
[out]	dr_root_dir	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 MAXIMUM_PATH.
[out]	dr_mode	If the process is registered, the mode provided at registration. Callers can pass NULL if this value is not needed.
[out]	debug	If the process is registered, the debug flag provided at registration. Callers can pass NULL if this value is not needed.
[out]	dr_options	If 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_registered_process_iterator_start()

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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
[in]	global	Whether 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_registered_process_iterator_stop()

DR_EXPORT void dr_registered_process_iterator_stop ( dr_registered_process_iterator_t * iter )

Stops and frees a registered process iterator.

Parameters

[in] iter A registered process iterator created with dr_registered_process_iterator_start()

Note: Not yet available on Linux or MacOS.

◆ dr_syswide_is_on()

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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those to use.
[in]	dr_root_dir	The root DynamoRIO directory.

Returns: Whether systemwide injection is enabled.

Note: Not yet available on Linux or MacOS.

◆ dr_unregister_client()

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_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
[in]	client_id	The unique client ID provided at client registration.

Returns: A dr_config_status_t code indicating the result of unregistration.

◆ dr_unregister_process()

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_name	A 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]	pid	A 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]	global	Whether 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_platform	Configurations 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_unregister_syswide()

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_platform	Configurations are kept separate for 32-bit processes and 64-bit processes. This parameter allows selecting which of those to use.
[in]	dr_root_dir	The 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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DR_MAX_OPTIONS_LENGTH

Typedef Documentation

◆ dr_config_client_t

Enumeration Type Documentation

◆ dr_config_status_t

◆ dr_operation_mode_t

◆ dr_platform_t

Function Documentation

◆ dr_client_iterator_hasnext()

◆ dr_client_iterator_next()

◆ dr_client_iterator_next_ex()

◆ dr_client_iterator_start()

◆ dr_client_iterator_stop()

◆ dr_config_status_code_to_string()

◆ dr_get_client_info()

◆ dr_get_client_info_ex()

◆ dr_get_config_dir()

◆ dr_nudge_all()

◆ dr_nudge_pid()

◆ dr_nudge_process()

◆ dr_num_registered_clients()

◆ dr_process_is_registered()

◆ dr_register_client()

◆ dr_register_client_ex()

◆ dr_register_inject_paths()

◆ dr_register_process()

◆ dr_register_syswide()

◆ dr_registered_process_iterator_hasnext()

◆ dr_registered_process_iterator_next()

◆ dr_registered_process_iterator_start()

◆ dr_registered_process_iterator_stop()

◆ dr_syswide_is_on()

◆ dr_unregister_client()

◆ dr_unregister_process()

◆ dr_unregister_syswide()