dr_config.h File Reference

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

Defines

#define DR_MAX_OPTIONS_LENGTH   512

Enumerations

enum dr_operation_mode_t {
  DR_MODE_NONE = 0,
  DR_MODE_CODE_MANIPULATION = 1
}

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
}

enum dr_platform_t {
  DR_PLATFORM_DEFAULT,
  DR_PLATFORM_32BIT,
  DR_PLATFORM_64BIT
}

Functions

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

dr_config_status_t dr_register_syswide (dr_platform_t dr_platform, const char *dr_root_dir)

dr_config_status_t dr_unregister_syswide (dr_platform_t dr_platform, const char *dr_root_dir)

bool dr_syswide_is_on (dr_platform_t dr_platform, const char *dr_root_dir)

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_registered_process_iterator_t * dr_registered_process_iterator_start (dr_platform_t dr_platform, bool global)

bool dr_registered_process_iterator_hasnext (dr_registered_process_iterator_t *iter)

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)

void dr_registered_process_iterator_stop (dr_registered_process_iterator_t *iter)

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_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)

size_t dr_num_registered_clients (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)

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_client_iterator_t * dr_client_iterator_start (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)

bool dr_client_iterator_hasnext (dr_client_iterator_t *iter)

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)

void dr_client_iterator_stop (dr_client_iterator_t *iter)

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_config_status_t dr_nudge_pid (process_id_t process_id, client_id_t client_id, uint64 arg, uint timeout_ms)

dr_config_status_t dr_nudge_all (client_id_t client_id, uint64 arg, uint timeout_ms, int *nudge_count)

Detailed Description

Deployment API for Windows. 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.

Define Documentation

#define DR_MAX_OPTIONS_LENGTH 512

Maximum length of a registered process's options string

Enumeration Type Documentation

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.

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.

enum dr_platform_t

Allow targeting both WOW64 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 or WOW64 processes).
DR_PLATFORM_64BIT	64-bit settings (for native 64-bit processes).

Function Documentation

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

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 MAX_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_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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) 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()

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_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_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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) 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 MAX_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_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:: Nudging 64-bit processes is not yet supported.

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:: Nudging 64-bit processes is not yet supported.

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:: Nudging 64-bit processes is not yet supported.

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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) 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.

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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) 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 MAX_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_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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.
`[in]`	client_id	A client_id_t uniquely identifying the client. DynamoRIO provides the client ID as a parameter to dr_init(). 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 MAX_PATH. The client path may not include any semicolons.
`[in]`	client_options	A NULL-terminated string specifying options that are available to the client via dr_get_options(). The string length cannot exceed DR_MAX_OPTIONS_LENGTH. The client options may not include any semicolons.

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

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.

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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 MAX_PATH.
`[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 on 64-bit Windows for 32-bit (WOW64) 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_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 on 64-bit Windows for 32-bit (WOW64) processes and 64-bit processes. This parameter allows selecting which of those to use.
`[in]`	dr_root_dir	The root DynamoRIO directory (used to locate drpreinject.dll).

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

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

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

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 on 64-bit Windows for 32-bit (WOW64) processes and 64-bit processes. This parameter allows selecting which of those configurations to check.
`[in]`	global	Whether global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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()

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

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 on 64-bit Windows for 32-bit (WOW64) processes and 64-bit processes. This parameter allows selecting which of those to use.
`[in]`	dr_root_dir	The root DynamoRIO directory (used to locate drpreinject.dll).

Returns:: Whether systemwide injection is enabled.

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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) 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_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 global config files, stored in a dir pointed at by the DYNAMORIO_HOME registry key, should be used, or local config files private to the current user. 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 on 64-bit Windows for 32-bit (WOW64) processes and 64-bit processes. This parameter allows selecting which of those configurations to unset.

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_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 on 64-bit Windows for 32-bit (WOW64) processes and 64-bit processes. This parameter allows selecting which of those to use.
`[in]`	dr_root_dir	The root DynamoRIO directory (used to locate drpreinject.dll).

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.


Defines
#define	DR_MAX_OPTIONS_LENGTH 512
Enumerations
enum	dr_operation_mode_t { DR_MODE_NONE = 0, DR_MODE_CODE_MANIPULATION = 1 }
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 }
enum	dr_platform_t { DR_PLATFORM_DEFAULT, DR_PLATFORM_32BIT, DR_PLATFORM_64BIT }
Functions
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_config_status_t	dr_unregister_process (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)
dr_config_status_t	dr_register_syswide (dr_platform_t dr_platform, const char *dr_root_dir)
dr_config_status_t	dr_unregister_syswide (dr_platform_t dr_platform, const char *dr_root_dir)
bool	dr_syswide_is_on (dr_platform_t dr_platform, const char *dr_root_dir)
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_registered_process_iterator_t *	dr_registered_process_iterator_start (dr_platform_t dr_platform, bool global)
bool	dr_registered_process_iterator_hasnext (dr_registered_process_iterator_t *iter)
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)
void	dr_registered_process_iterator_stop (dr_registered_process_iterator_t *iter)
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_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)
size_t	dr_num_registered_clients (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)
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_client_iterator_t *	dr_client_iterator_start (const char *process_name, process_id_t pid, bool global, dr_platform_t dr_platform)
bool	dr_client_iterator_hasnext (dr_client_iterator_t *iter)
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)
void	dr_client_iterator_stop (dr_client_iterator_t *iter)
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_config_status_t	dr_nudge_pid (process_id_t process_id, client_id_t client_id, uint64 arg, uint timeout_ms)
dr_config_status_t	dr_nudge_all (client_id_t client_id, uint64 arg, uint timeout_ms, int *nudge_count)