dr_modules.h File Reference

Application module (library) querying routines. More...

Data Structures
union	_version_number_t
struct	_module_names_t
struct	_module_segment_data_t
struct	_module_data_t
struct	_dr_module_import_t
struct	_dr_symbol_import_t
struct	_dr_symbol_export_t
struct	_dr_export_info_t

Typedefs
typedef union _version_number_t	version_number_t
typedef struct _module_names_t	module_names_t
typedef void *	dr_module_iterator_t
typedef struct _module_segment_data_t	module_segment_data_t
typedef struct _dr_module_import_t	dr_module_import_t
typedef struct _dr_symbol_import_t	dr_symbol_import_t
typedef struct _dr_symbol_export_t	dr_symbol_export_t
typedef struct _dr_export_info_t	dr_export_info_t

Functions
DR_API module_data_t *	dr_lookup_module (byte *pc)
DR_API module_data_t *	dr_lookup_module_by_name (const char *name)
DR_API module_data_t *	dr_get_main_module (void)
DR_API dr_module_iterator_t *	dr_module_iterator_start (void)
DR_API bool	dr_module_iterator_hasnext (dr_module_iterator_t *mi)
DR_API module_data_t *	dr_module_iterator_next (dr_module_iterator_t *mi)
DR_API void	dr_module_iterator_stop (dr_module_iterator_t *mi)
DR_API module_data_t *	dr_copy_module_data (const module_data_t *data)
DR_API void	dr_free_module_data (module_data_t *data)
const DR_API char *	dr_module_preferred_name (const module_data_t *data)
DR_API bool	dr_module_contains_addr (const module_data_t *data, app_pc addr)
DR_API dr_module_import_iterator_t *	dr_module_import_iterator_start (module_handle_t handle)
DR_API bool	dr_module_import_iterator_hasnext (dr_module_import_iterator_t *iter)
DR_API dr_module_import_t *	dr_module_import_iterator_next (dr_module_import_iterator_t *iter)
DR_API void	dr_module_import_iterator_stop (dr_module_import_iterator_t *iter)
DR_API dr_symbol_import_iterator_t *	dr_symbol_import_iterator_start (module_handle_t handle, dr_module_import_desc_t *from_module)
DR_API bool	dr_symbol_import_iterator_hasnext (dr_symbol_import_iterator_t *iter)
DR_API dr_symbol_import_t *	dr_symbol_import_iterator_next (dr_symbol_import_iterator_t *iter)
DR_API void	dr_symbol_import_iterator_stop (dr_symbol_import_iterator_t *iter)
DR_API dr_symbol_export_iterator_t *	dr_symbol_export_iterator_start (module_handle_t handle)
DR_API bool	dr_symbol_export_iterator_hasnext (dr_symbol_export_iterator_t *iter)
DR_API dr_symbol_export_t *	dr_symbol_export_iterator_next (dr_symbol_export_iterator_t *iter)
DR_API void	dr_symbol_export_iterator_stop (dr_symbol_export_iterator_t *iter)
DR_API bool	dr_lookup_module_section (module_handle_t lib, byte *pc, IMAGE_SECTION_HEADER *section_out)
DR_API bool	dr_module_set_should_instrument (module_handle_t handle, bool should_instrument)
DR_API bool	dr_module_should_instrument (module_handle_t handle)
DR_API generic_func_t	dr_get_proc_address (module_handle_t lib, const char *name)
DR_API bool	dr_get_proc_address_ex (module_handle_t lib, const char *name, dr_export_info_t *info DR_PARAM_OUT, size_t info_len)

Detailed Description

Application module (library) querying routines.

Typedef Documentation

dr_export_info_t

typedef struct _dr_export_info_t dr_export_info_t

Data structure used by dr_get_proc_address_ex() to retrieve information about an exported symbol.

dr_module_import_t

typedef struct _dr_module_import_t dr_module_import_t

Module import data returned from dr_module_import_iterator_next().

String fields point into the importing module image. Robust clients should use DR_TRY_EXCEPT while inspecting the strings in case the module is partially mapped or the app racily unmaps it. The iterator routines themselves handle faults by stopping the iteration.

Note

ELF does not import directly from other modules.

dr_module_iterator_t

typedef void* dr_module_iterator_t

For dr_module_iterator_* interface

dr_symbol_export_t

typedef struct _dr_symbol_export_t dr_symbol_export_t

Symbol export data returned from dr_symbol_export_iterator_next().

String fields point into the exporting module image. Robust clients should use DR_TRY_EXCEPT while inspecting the strings in case the module is partially mapped or the app racily unmaps it.

On Windows, the address in addr may not be inside the exporting module if it is a forward and has been patched by the loader. In that case, forward will be NULL.

dr_symbol_import_t

typedef struct _dr_symbol_import_t dr_symbol_import_t

Symbol import data returned from dr_symbol_import_iterator_next().

String fields point into the importing module image. Robust clients should use DR_TRY_EXCEPT while inspecting the strings in case the module is partially mapped or the app racily unmaps it.

module_names_t

typedef struct _module_names_t module_names_t

Holds the names of a module. This structure contains multiple fields corresponding to different sources of a module name. Note that some of these names may not exist for certain modules. It is highly likely, however, that at least one name is available. Use dr_module_preferred_name() on the parent _module_data_t to get the preferred name of the module.

module_segment_data_t

typedef struct _module_segment_data_t module_segment_data_t

Holds information on a segment of a loaded module.

version_number_t

typedef union _version_number_t version_number_t

Used to hold .rsrc section version number information. This number is usually presented as p1.p2.p3.p4 by PE parsing tools.

Function Documentation

dr_copy_module_data()

DR_API module_data_t* dr_copy_module_data

(

const module_data_t *

data

)

Makes a copy of data. Copy must be freed with dr_free_module_data(). Useful for making persistent copies of module_data_t's received as part of image load and unload event callbacks.

dr_free_module_data()

DR_API void dr_free_module_data

(

module_data_t *

data

)

Frees a module_data_t returned by dr_module_iterator_next(), dr_lookup_module(), dr_lookup_module_by_name(), or dr_copy_module_data().

Note

Should NOT be used with a module_data_t obtained as part of a module load or unload event.

dr_get_main_module()

DR_API module_data_t* dr_get_main_module

(

void

)

Looks up module data for the main executable.

Note

Returned module_data_t must be freed with dr_free_module_data().

dr_get_proc_address()

DR_API generic_func_t dr_get_proc_address	(	module_handle_t	lib,
		const char *	name
	)

Returns the entry point of the exported function with the given name in the module with the given base. Returns NULL on failure.

On Linux, when we say "exported" we mean present in the dynamic symbol table (.dynsym). Global functions and variables in an executable (as opposed to a library) are not exported by default. If an executable is built with the -rdynamic flag to gcc, its global symbols will be present in .dynsym and dr_get_proc_address() will locate them. Otherwise, the drsyms Extension (see Symbol Access Library) must be used to locate the symbols. drsyms searches the debug symbol table (.symtab) in addition to .dynsym.

Note

On Linux this ignores symbol preemption by other modules and only examines the specified module.

On Linux, in order to handle indirect code objects, use dr_get_proc_address_ex().

dr_get_proc_address_ex()

DR_API bool dr_get_proc_address_ex	(	module_handle_t	lib,
		const char *	name,
		dr_export_info_t *info	DR_PARAM_OUT,
		size_t	info_len
	)

Returns information in info about the symbol name exported by the module lib. Returns false if the symbol is not found. See the information in dr_get_proc_address() about what an "exported" function is on Linux.

Note

On Linux this ignores symbol preemption by other modules and only examines the specified module.

dr_lookup_module()

DR_API module_data_t* dr_lookup_module

(

byte *

pc

)

Looks up the module containing pc. If a module containing pc is found returns a module_data_t describing that module. Returns NULL if pc is outside all known modules, which is the case for most dynamically generated code. Can be used to obtain a module_handle_t for dr_lookup_module_section() or dr_get_proc_address() via the handle field inside module_data_t.

Note

Returned module_data_t must be freed with dr_free_module_data().

dr_lookup_module_by_name()

DR_API module_data_t* dr_lookup_module_by_name

(

const char *

name

)

Looks up the module with name name ignoring case. If an exact name match is found returns a module_data_t describing that module else returns NULL. User must call dr_free_module_data() on the returned module_data_t once finished. Can be used to obtain a module_handle_t for dr_get_proc_address().

Note

Returned module_data_t must be freed with dr_free_module_data().

dr_lookup_module_section()

DR_API bool dr_lookup_module_section	(	module_handle_t	lib,
		byte *	pc,
		IMAGE_SECTION_HEADER *	section_out
	)

Returns whether pc is within a section within the module in section_found and information about that section in section_out.

Note

Not yet available on Linux.

dr_module_contains_addr()

DR_API bool dr_module_contains_addr	(	const module_data_t *	data,
		app_pc	addr
	)

Returns whether addr is contained inside any segment of the module data. We recommend using this routine rather than checking against the start and end fields of data, as modules are not always contiguous.

dr_module_import_iterator_hasnext()

DR_API bool dr_module_import_iterator_hasnext

(

dr_module_import_iterator_t *

iter

)

Returns true if there is another module import in the iterator.

Note

ELF does not import directly from other modules.

dr_module_import_iterator_next()

DR_API dr_module_import_t* dr_module_import_iterator_next

(

dr_module_import_iterator_t *

iter

)

Advances the passed-in iterator and returns the current module import in the iterator. The pointer returned is only valid until the next call to dr_module_import_iterator_next() or dr_module_import_iterator_stop().

Note

ELF does not import directly from other modules.

dr_module_import_iterator_start()

DR_API dr_module_import_iterator_t* dr_module_import_iterator_start

(

module_handle_t

handle

)

Creates a module import iterator. Iterates over the list of modules that a given module imports from.

Note

ELF does not import directly from other modules.

dr_module_import_iterator_stop()

DR_API void dr_module_import_iterator_stop

(

dr_module_import_iterator_t *

iter

)

Stops import iteration and frees a module import iterator.

Note

ELF does not import directly from other modules.

dr_module_iterator_hasnext()

DR_API bool dr_module_iterator_hasnext

(

dr_module_iterator_t *

mi

)

Returns true if there is another loaded module in the iterator.

dr_module_iterator_next()

DR_API module_data_t* dr_module_iterator_next

(

dr_module_iterator_t *

mi

)

Retrieves the module_data_t for the next loaded module in the iterator. User must call dr_free_module_data() on the returned module_data_t once finished.

Note

Returned module_data_t must be freed with dr_free_module_data().

dr_module_iterator_start()

DR_API dr_module_iterator_t* dr_module_iterator_start

(

void

)

Initialize a new module iterator. The returned module iterator contains a snapshot of the modules loaded at the time it was created. Use dr_module_iterator_hasnext() and dr_module_iterator_next() to walk the loaded modules. Call dr_module_iterator_stop() when finished to release the iterator.

Note

The iterator does not prevent modules from being loaded or unloaded while the iterator is being walked.

dr_module_iterator_stop()

DR_API void dr_module_iterator_stop

(

dr_module_iterator_t *

mi

)

User should call this routine to free the module iterator.

dr_module_preferred_name()

const DR_API char* dr_module_preferred_name

(

const module_data_t *

data

)

Returns the preferred name for the module described by data from data->module_names.

dr_module_set_should_instrument()

DR_API bool dr_module_set_should_instrument	(	module_handle_t	handle,
		bool	should_instrument
	)

Set whether or not the module referred to by handle should be instrumented. If should_instrument is false, code from the module will not be passed to the basic block event. If traces are enabled, code from the module will still reach the trace event. Must be called from the module load event for the module referred to by handle.

Returns

whether successful.

Warning

Turning off instrumentation for modules breaks clients and extensions, such as drwrap, that expect to see every instruction.

dr_module_should_instrument()

DR_API bool dr_module_should_instrument

(

module_handle_t

handle

)

Return whether code from the module should be instrumented, meaning passed to the basic block event.

dr_symbol_export_iterator_hasnext()

DR_API bool dr_symbol_export_iterator_hasnext

(

dr_symbol_export_iterator_t *

iter

)

Returns true if there is another exported symbol in the iterator.

dr_symbol_export_iterator_next()

DR_API dr_symbol_export_t* dr_symbol_export_iterator_next

(

dr_symbol_export_iterator_t *

iter

)

Returns the next exported symbol. The returned pointer is valid until the next call to dr_symbol_export_iterator_next() or dr_symbol_export_iterator_stop().

dr_symbol_export_iterator_start()

DR_API dr_symbol_export_iterator_t* dr_symbol_export_iterator_start

(

module_handle_t

handle

)

Creates an iterator over symbols exported by a module. The iterator returned is invalid until after the first call to dr_symbol_export_iterator_next().

Note

To iterate over all symbols in a module and not just those exported, use the Symbol Access Library.

dr_symbol_export_iterator_stop()

DR_API void dr_symbol_export_iterator_stop

(

dr_symbol_export_iterator_t *

iter

)

Stops symbol export iteration and frees the iterator.

dr_symbol_import_iterator_hasnext()

DR_API bool dr_symbol_import_iterator_hasnext

(

dr_symbol_import_iterator_t *

iter

)

Returns true if there is another imported symbol in the iterator.

dr_symbol_import_iterator_next()

DR_API dr_symbol_import_t* dr_symbol_import_iterator_next

(

dr_symbol_import_iterator_t *

iter

)

Returns the next imported symbol. The returned pointer is valid until the next call to dr_symbol_import_iterator_next() or dr_symbol_import_iterator_stop().

dr_symbol_import_iterator_start()

DR_API dr_symbol_import_iterator_t* dr_symbol_import_iterator_start	(	module_handle_t	handle,
		dr_module_import_desc_t *	from_module
	)

Creates an iterator over symbols imported by a module. If from_module is NULL, all imported symbols are yielded, regardless of which module they were imported from.

On Windows, from_module is obtained from a dr_module_import_t and used to iterate over all of the imports from a specific module.

The iterator returned is invalid until after the first call to dr_symbol_import_iterator_next().

Note

On Windows, symbols imported from delay-loaded DLLs are not included yet.

dr_symbol_import_iterator_stop()

DR_API void dr_symbol_import_iterator_stop

(

dr_symbol_import_iterator_t *

iter

)

Stops symbol import iteration and frees the iterator.