pub unsafe extern "C" fn dr_register_process(
process_name: *const c_char,
pid: process_id_t,
global: bool_,
dr_root_dir: *const c_char,
dr_mode: dr_operation_mode_t,
debug: bool_,
dr_platform: dr_platform_t,
dr_options: *const c_char,
) -> dr_config_status_tExpand description
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 \p pid != 0), call dr_get_config_dir() prior to creating the child process (and prior to calling this routine) and pass true for \p alternative_local. For multi-step, the caller must set the DYNAMORIO_CONFIGDIR environment variable before calling this routine.
\param[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).
\param[in] pid A process id of a target process, typically just created and suspended via dr_inject_process_exit(). If \p pid != 0, a one-time configuration is created just for it. If \p pid == 0, a general configuration is created for all future instances of process_name.
\param[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.
\param[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.
\param[in] dr_mode Specifies the mode under which DynamoRIO should operate. See dr_operation_mode_t.
\param[in] debug If true, a DynamoRIO debug build will be used; otherwise, a release build will be used.
\param[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.
\param[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.
\return 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 \p pid == 0) persists across reboots until explicitly unregistered.