_drsys_options_t Struct Reference

#include <drsyscall.h>

Data Fields
size_t	struct_size
bool	analyze_unknown_syscalls
bool	syscall_dword_granularity
bool	syscall_sentinels
bool(*	is_byte_addressable )(byte *addr)
bool(*	is_byte_defined )(byte *addr)
bool(*	is_byte_undefined )(byte *addr)
bool(*	is_register_defined )(reg_id_t reg)
bool	verify_sysnums
app_pc(*	lookup_internal_symbol )(const module_data_t *mod, const char *sym)
bool	syscall_driver
const char *	sysnum_file
bool	skip_internal_tables

Detailed Description

Specifies parameters controlling the behavior of Dr. Syscall to drsys_init().

Field Documentation

analyze_unknown_syscalls

bool _drsys_options_t::analyze_unknown_syscalls

Dr. Syscall does not have information on every system call. For unknown syscalls, if this parameter is set, then a pre- and post-syscall memory comparison will be used to identify output parameters. Input parameters will remain unknown. When using this parameter, we recommend providing callbacks for is_byte_addressable(), is_byte_defined(), and is_register_defined(), if possible, to achieve greater accuracy.

is_byte_addressable

bool(* _drsys_options_t::is_byte_addressable) (byte *addr)

Provides a query routine for whether a byte is addressable, i.e., allocated and safe to access. If analyze_unknown_syscalls is on, the quality of unknown parameter analysis increases substantially if information on whether registers and memory contain valid, initialized information is available.

is_byte_defined

bool(* _drsys_options_t::is_byte_defined) (byte *addr)

Provides a query routine for whether a byte is defined, i.e., allocated, safe to access, and initialized. If analyze_unknown_syscalls is on, the quality of unknown parameter analysis increases substantially if information on whether registers and memory contain valid, initialized information is available.

is_byte_undefined

bool(* _drsys_options_t::is_byte_undefined) (byte *addr)

Provides a query routine for whether a byte is undefined, i.e., allocated and safe to access yet uninitialized. If analyze_unknown_syscalls is on, the quality of unknown parameter analysis increases substantially if information on whether registers and memory contain valid, initialized information is available. If this is not provided but is_byte_addressable and is_byte_defined both are, those two will be called in concert to provide this information.

is_register_defined

bool(* _drsys_options_t::is_register_defined) (reg_id_t reg)

Provides a query routine for whether a register is defined, i.e., contains a fully initialized value. If analyze_unknown_syscalls is on, the quality of unknown parameter analysis increases substantially if information on whether registers and memory contain valid, initialized information is available.

lookup_internal_symbol

app_pc(* _drsys_options_t::lookup_internal_symbol) (const module_data_t *mod, const char *sym)

This is an internal-only option that is reserved for developer use.

skip_internal_tables

bool _drsys_options_t::skip_internal_tables

Whether to use internal syscall tables if they match the underlying kernel.

struct_size

size_t _drsys_options_t::struct_size

For compatibility. Set to sizeof(drsys_options_t).

syscall_driver

bool _drsys_options_t::syscall_driver

This is an internal-only option that is reserved for developer use.

syscall_dword_granularity

bool _drsys_options_t::syscall_dword_granularity

If analyze_unknown_syscalls is on and this parameter is on, when changes are detected, the containing dword (32 bits) are considered to have changed.

syscall_sentinels

bool _drsys_options_t::syscall_sentinels

If analyze_unknown_syscalls is on and this parameter is on, sentinels are used to detect writes and reduce false positives, in particular for uninitialized reads. However, enabling this option can potentially result in incorrect behavior if definedness information is incorrect or application threads read syscall parameter info simultaneously.

sysnum_file

const char* _drsys_options_t::sysnum_file

Points at the path to a text file that contains system call numbers. This is intended to provide a mechanism to support new versions of operating systems, Windows in particular, with a simple data file update. The file is only examined if the built-in system call tables do not match the current operating system.

This file can be generated using drsys_find_sysnum_dlls() and drsys_generate_sysnum_file().

The file format is text line-based. The first line must contain the string "DrSyscall Number File" (DRSYS_SYSNUM_FILE_HEADER). The second line must contain a single integer indicating the format version (DRSYS_SYSNUM_FILE_VERSION). The third line contains a string indicating which system call (for Windows, it must be an ntoskrnl system call with a wrapper present in ntdll.dll) to use as the differentiator among versions. The body of the file contains lists of system calls of the format "name=number", with the number again in hexadecimal "0x" format. Each list begins with a line "START=" with the value of the differentiator that selects that list after the "=" sign. Each list concludes with a line "=END" (DRSYS_SYSNUM_FILE_FOOTER). For example:

DrSyscall Number File
1
NtGetContextThread
START=0xe5
NtBindCompositionSurface=0x1121
NtCompositionInputThread=0x1122
NtCompositionSetDropTarget=0x1123
NtUserCallNoParam.CREATEMENU=0x0
...
=END
START=0xe6
NtBindCompositionSurface=0x1120
NtCompositionInputThread=0x1121
NtCompositionSetDropTarget=0x1122
NtUserCallNoParam.CREATEMENU=0x0
...
=END

This file is currently only honored on Windows.

verify_sysnums

bool _drsys_options_t::verify_sysnums

This is an internal-only option that is reserved for developer use.

---

The documentation for this struct was generated from the following file:

• drsyscall.h