Header for Dr. Syscall: System Call Monitoring Extension. More...

#include "drmemory_framework.h"

Data Structures
struct	_drsys_sysnum_t

struct	_drsys_arg_t

struct	_drsys_options_t

Macros
#define	DRMGR_PRIORITY_NAME_DRSYS "drsyscall"

#define	DRMGR_PRIORITY_NAME_DRSYS_LAST "drsyscall_last"

#define	DRSYS_SYSNUM_FILE_VERSION 1

#define	DRSYS_SYSNUM_FILE_HEADER "DrSyscall Number File"

#define	DRSYS_SYSNUM_FILE_FOOTER "=END"

Typedefs
typedef struct _drsys_syscall_t	drsys_syscall_t

typedef struct _drsys_sysnum_t	drsys_sysnum_t

typedef struct _drsys_arg_t	drsys_arg_t

typedef struct _drsys_options_t	drsys_options_t

typedef bool(*	drsys_iter_cb_t) (drsys_arg_t arg, void user_data)

Enumerations
enum	{ DRMGR_PRIORITY_PRESYS_DRSYS = -100, DRMGR_PRIORITY_POSTSYS_DRSYS = -100, DRMGR_PRIORITY_POSTSYS_DRSYS_LAST = 10000, DRMGR_PRIORITY_MODLOAD_DRSYS = -100 }

enum	drsys_param_mode_t { DRSYS_PARAM_IN = 0x01, DRSYS_PARAM_OUT = 0x02, DRSYS_PARAM_BOUNDS = 0x04, DRSYS_PARAM_RETVAL = 0x08, DRSYS_PARAM_INLINED = 0x10 }

enum	drsys_param_type_t { DRSYS_TYPE_INVALID, DRSYS_TYPE_UNKNOWN, DRSYS_TYPE_VOID, DRSYS_TYPE_BOOL, DRSYS_TYPE_INT, DRSYS_TYPE_SIGNED_INT, DRSYS_TYPE_UNSIGNED_INT, DRSYS_TYPE_SIZE_T, DRSYS_TYPE_HANDLE, DRSYS_TYPE_NTSTATUS, DRSYS_TYPE_ATOM, DRSYS_TYPE_LCID, DRSYS_TYPE_LPARAM, DRSYS_TYPE_HMODULE, DRSYS_TYPE_HFILE, DRSYS_TYPE_POINTER, DRSYS_TYPE_STRUCT, DRSYS_TYPE_CSTRING, DRSYS_TYPE_CWSTRING, DRSYS_TYPE_CARRAY, DRSYS_TYPE_CWARRAY, DRSYS_TYPE_CSTRARRAY, DRSYS_TYPE_UNICODE_STRING, DRSYS_TYPE_LARGE_STRING, DRSYS_TYPE_OBJECT_ATTRIBUTES, DRSYS_TYPE_SECURITY_DESCRIPTOR, DRSYS_TYPE_SECURITY_QOS, DRSYS_TYPE_PORT_MESSAGE, DRSYS_TYPE_CONTEXT, DRSYS_TYPE_EXCEPTION_RECORD, DRSYS_TYPE_DEVMODEW, DRSYS_TYPE_WNDCLASSEXW, DRSYS_TYPE_CLSMENUNAME, DRSYS_TYPE_MENUITEMINFOW, DRSYS_TYPE_ALPC_PORT_ATTRIBUTES, DRSYS_TYPE_ALPC_SECURITY_ATTRIBUTES, DRSYS_TYPE_LOGFONTW, DRSYS_TYPE_NONCLIENTMETRICSW, DRSYS_TYPE_ICONMETRICSW, DRSYS_TYPE_SERIALKEYSW, DRSYS_TYPE_SOCKADDR, DRSYS_TYPE_MSGHDR, DRSYS_TYPE_MSGBUF, DRSYS_TYPE_LARGE_INTEGER, DRSYS_TYPE_ULARGE_INTEGER, DRSYS_TYPE_IO_STATUS_BLOCK, DRSYS_TYPE_FUNCTION, DRSYS_TYPE_BITMAPINFO, DRSYS_TYPE_ALPC_CONTEXT_ATTRIBUTES, DRSYS_TYPE_ALPC_MESSAGE_ATTRIBUTES, DRSYS_TYPE_T2_SET_PARAMETERS }

enum	drsys_syscall_type_t { DRSYS_SYSCALL_TYPE_KERNEL, DRSYS_SYSCALL_TYPE_USER, DRSYS_SYSCALL_TYPE_GRAPHICS }

enum	drsys_gateway_t

Functions
DR_EXPORT drmf_status_t	drsys_init (client_id_t client_id, drsys_options_t *options)

DR_EXPORT drmf_status_t	drsys_exit (void)

DR_EXPORT drmf_status_t	drsys_filter_syscall (drsys_sysnum_t sysnum)

DR_EXPORT drmf_status_t	drsys_filter_all_syscalls (void)

DR_EXPORT drmf_status_t	drsys_name_to_syscall (const char name, DR_PARAM_OUT drsys_syscall_t *syscall)

DR_EXPORT drmf_status_t	drsys_number_to_syscall (drsys_sysnum_t sysnum, DR_PARAM_OUT drsys_syscall_t **syscall)

DR_EXPORT drmf_status_t	drsys_syscall_name (drsys_syscall_t syscall, DR_PARAM_OUT const char *name)

DR_EXPORT drmf_status_t	drsys_syscall_number (drsys_syscall_t syscall, DR_PARAM_OUT drsys_sysnum_t sysnum)

DR_EXPORT drmf_status_t	drsys_syscall_type (drsys_syscall_t syscall, DR_PARAM_OUT drsys_syscall_type_t type)

DR_EXPORT drmf_status_t	drsys_syscall_is_known (drsys_syscall_t syscall, DR_PARAM_OUT bool known)

DR_EXPORT drmf_status_t	drsys_syscall_succeeded (drsys_syscall_t syscall, reg_t result, DR_PARAM_OUT bool success)

DR_EXPORT drmf_status_t	drsys_syscall_return_type (drsys_syscall_t syscall, DR_PARAM_OUT drsys_param_type_t type)

DR_EXPORT drmf_status_t	drsys_handle_is_current_process (HANDLE h, bool *current)

static bool	drsys_sysnums_equal (drsys_sysnum_t num1, drsys_sysnum_t num2)

DR_EXPORT drmf_status_t	drsys_syscall_gateway (drsys_gateway_t *method)

DR_EXPORT drmf_status_t	drsys_cur_syscall (void drcontext, DR_PARAM_OUT drsys_syscall_t *syscall)

DR_EXPORT drmf_status_t	drsys_cur_syscall_result (void drcontext, DR_PARAM_OUT bool success, DR_PARAM_OUT uint64 value, DR_PARAM_OUT uint error_code)

DR_EXPORT drmf_status_t	drsys_pre_syscall_arg (void drcontext, uint argnum, DR_PARAM_OUT ptr_uint_t value)

DR_EXPORT drmf_status_t	drsys_pre_syscall_arg64 (void drcontext, uint argnum, DR_PARAM_OUT uint64 value)

DR_EXPORT drmf_status_t	drsys_get_mcontext (void drcontext, DR_PARAM_OUT dr_mcontext_t *mc)

DR_EXPORT drmf_status_t	drsys_iterate_syscalls (bool(cb)(drsys_sysnum_t sysnum, drsys_syscall_t syscall, void user_data), void user_data)

DR_EXPORT drmf_status_t	drsys_iterate_arg_types (drsys_syscall_t syscall, drsys_iter_cb_t cb, void user_data)

DR_EXPORT drmf_status_t	drsys_iterate_args (void drcontext, drsys_iter_cb_t cb, void user_data)

DR_EXPORT drmf_status_t	drsys_iterate_memargs (void drcontext, drsys_iter_cb_t cb, void user_data)

DR_EXPORT drmf_status_t	drsys_find_sysnum_libs (DR_PARAM_OUT char *sysnum_lib_paths, DR_PARAM_INOUT size_t num_sysnum_libs)

DR_EXPORT drmf_status_t	drsys_generate_sysnum_file (void drcontext, const char sysnum_lib_paths, size_t num_sysnum_libs, const char outfile, const char *cache_dir)

Detailed Description

Header for Dr. Syscall: System Call Monitoring Extension.

Macro Definition Documentation

◆ DRMGR_PRIORITY_NAME_DRSYS

#define DRMGR_PRIORITY_NAME_DRSYS "drsyscall"

Name of drsyscall pre-syscall and post-syscall events that occur prior to iteration being allowed.

◆ DRMGR_PRIORITY_NAME_DRSYS_LAST

#define DRMGR_PRIORITY_NAME_DRSYS_LAST "drsyscall_last"

Name of drsyscall post-syscall last-chance event.

◆ DRSYS_SYSNUM_FILE_FOOTER

#define DRSYS_SYSNUM_FILE_FOOTER "=END"

The separator string indicating the end of a sequence of system call numbers in the file specified by drsys_options_t.sysnum_file.

◆ DRSYS_SYSNUM_FILE_HEADER

#define DRSYS_SYSNUM_FILE_HEADER "DrSyscall Number File"

The header string of the file specified by drsys_options_t.sysnum_file.

◆ DRSYS_SYSNUM_FILE_VERSION

#define DRSYS_SYSNUM_FILE_VERSION 1

The current version of the file specified by drsys_options_t.sysnum_file.

Typedef Documentation

◆ drsys_arg_t

typedef struct _drsys_arg_t drsys_arg_t

Describes a system call parameter or memory region.

◆ drsys_iter_cb_t

typedef bool(* drsys_iter_cb_t) (drsys_arg_t *arg, void *user_data)

Type of iterator callbacks.

◆ drsys_options_t

typedef struct _drsys_options_t drsys_options_t

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

◆ drsys_syscall_t

typedef struct _drsys_syscall_t drsys_syscall_t

Opaque "system call handle" type used to refer to a particular system call. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

◆ drsys_sysnum_t

typedef struct _drsys_sysnum_t drsys_sysnum_t

Representation of a system call number.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Priority of drsyscall events.

Enumerator
DRMGR_PRIORITY_PRESYS_DRSYS	Priority of the drsyscall pre-syscall and post-syscall events that are meant to take place before the corresponding events of a regular user of drsyscall. Dynamic iteration is not allowed until these events have taken place. Users of drsyscall should arrange their pre-syscall and post-syscall event callbacks to be called after the drsyscall event, unless they want to modify the pre-syscall arguments before they're stored or they want to modify the application's context, in which case their event should go beforehand.
DRMGR_PRIORITY_POSTSYS_DRSYS	See the comment for DRMGR_PRIORITY_PRESYS_DRSYS.
DRMGR_PRIORITY_POSTSYS_DRSYS_LAST	Priority of the drsyscall last-chance post-syscall event. This event must take place after any dynamic iteration of system call arguments, which means it must be after the post-syscall event in all users of drsyscall.
DRMGR_PRIORITY_MODLOAD_DRSYS	Priority of the drsyscall module load event. This event must take place before any user of drsyscall in order to populate the tables used by drsys_name_to_syscall().

◆ drsys_gateway_t

enum drsys_gateway_t

Indicates the primary method of invoking the kernel for a system call.

◆ drsys_param_mode_t

enum drsys_param_mode_t

Indicates whether a parameter is an input or an output. Used as a bitmask, so multiple of these can be set.

Enumerator
DRSYS_PARAM_IN	Input parameter.
DRSYS_PARAM_OUT	Output parameter.
DRSYS_PARAM_BOUNDS	May be IN or OUT. Used only in pre-syscall to indicate the size of an entire data structure, when only some fields are actually read or writen. Those fields will be presented as separate IN or OUT arguments which will of course overlap this one.
DRSYS_PARAM_RETVAL	Not used for memory iteration, only for type iteration, where the type of the return value is indicated if it is other than a status or error code.
DRSYS_PARAM_INLINED	If this flag is not set, the parameter is passed as a pointer to the specified type. If this flag is set, the parameter's value is passed in.

◆ drsys_param_type_t

enum drsys_param_type_t

Indicates the data type of a parameter. For the non-memarg iterators, a pointer type is implied whenever the mode is DRSYS_PARAM_OUT. Thus, a system call parameter of type DRSYS_TYPE_INT and mode DRSYS_PARAM_OUT can be assumed to be a pointer to an int.

Enumerator
DRSYS_TYPE_INVALID	This type field is not used for this iteration type.
DRSYS_TYPE_UNKNOWN	Unknown type.
DRSYS_TYPE_VOID	Void type.
DRSYS_TYPE_BOOL	Boolean type.
DRSYS_TYPE_INT	Integer type of unspecified signedness.
DRSYS_TYPE_SIGNED_INT	Signed integer type.
DRSYS_TYPE_UNSIGNED_INT	Unsigned integer type.
DRSYS_TYPE_SIZE_T	Size_t type
DRSYS_TYPE_HANDLE	Windows-only: kernel/GDI/user handle type.
DRSYS_TYPE_NTSTATUS	Windows-only: NTSTATUS Native API/RTL type.
DRSYS_TYPE_ATOM	Windows-only: ATOM type.
DRSYS_TYPE_LCID	Windows-only: LCID type.
DRSYS_TYPE_LPARAM	Windows-only: LPARAM type.
DRSYS_TYPE_HMODULE	Windows-only: HMODULE type.
DRSYS_TYPE_HFILE	Windows-only: HFILE type.
DRSYS_TYPE_POINTER	Pointer to an unspecified type.
DRSYS_TYPE_STRUCT	Unspecified structure type.
DRSYS_TYPE_CSTRING	Null-terminated string of characters (C string).
DRSYS_TYPE_CWSTRING	Null-terminated string of wide characters.
DRSYS_TYPE_CARRAY	Non-null-terminated string of characters.
DRSYS_TYPE_CWARRAY	Non-null-terminated string of wide characters.
DRSYS_TYPE_CSTRARRAY	Null-terminated array of C strings.
DRSYS_TYPE_UNICODE_STRING	UNICODE_STRING structure.
DRSYS_TYPE_LARGE_STRING	LARGE_STRING structure.
DRSYS_TYPE_OBJECT_ATTRIBUTES	OBJECT_ATTRIBUTES structure.
DRSYS_TYPE_SECURITY_DESCRIPTOR	SECURITY_DESCRIPTOR structure.
DRSYS_TYPE_SECURITY_QOS	SECURITY_QUALITY_OF_SERVICE structure
DRSYS_TYPE_PORT_MESSAGE	PORT_MESSAGE structure.
DRSYS_TYPE_CONTEXT	CONTEXT structure.
DRSYS_TYPE_EXCEPTION_RECORD	EXCEPTION_RECORD structure.
DRSYS_TYPE_DEVMODEW	DEVMODEW structure.
DRSYS_TYPE_WNDCLASSEXW	WNDCLASSEXW structure.
DRSYS_TYPE_CLSMENUNAME	CLSMENUNAME structure.
DRSYS_TYPE_MENUITEMINFOW	MENUITEMINFOW structure.
DRSYS_TYPE_ALPC_PORT_ATTRIBUTES	ALPC_PORT_ATTRIBUTES structure.
DRSYS_TYPE_ALPC_SECURITY_ATTRIBUTES	ALPC_SECURITY_ATTRIBUTES structure.
DRSYS_TYPE_LOGFONTW	LOGFONTW structure.
DRSYS_TYPE_NONCLIENTMETRICSW	NONCLIENTMETRICSW structure.
DRSYS_TYPE_ICONMETRICSW	ICONMETRICSW structure.
DRSYS_TYPE_SERIALKEYSW	SERIALKEYSW structure.
DRSYS_TYPE_SOCKADDR	struct sockaddr.
DRSYS_TYPE_MSGHDR	struct msghdr.
DRSYS_TYPE_MSGBUF	struct msgbuf.
DRSYS_TYPE_LARGE_INTEGER	LARGE_INTEGER structure.
DRSYS_TYPE_ULARGE_INTEGER	ULARGE_INTEGER structure.
DRSYS_TYPE_IO_STATUS_BLOCK	IO_STATUS_BLOCK structure.
DRSYS_TYPE_FUNCTION	Function of unspecified signature.
DRSYS_TYPE_BITMAPINFO	BITMAPINFO structure.
DRSYS_TYPE_ALPC_CONTEXT_ATTRIBUTES	ALPC_CONTEXT_ATTRIBUTES structure.
DRSYS_TYPE_ALPC_MESSAGE_ATTRIBUTES	ALPC_MESSAGE_ATTRIBUTES structure.
DRSYS_TYPE_T2_SET_PARAMETERS	T2_SET_PARAMETERS structure.

◆ drsys_syscall_type_t

enum drsys_syscall_type_t

Indicates the category of system call. Relevant to Windows only.

Enumerator
DRSYS_SYSCALL_TYPE_KERNEL	The kernel proper (ntoskrnl for Windows).
DRSYS_SYSCALL_TYPE_USER	A user-related system call.
DRSYS_SYSCALL_TYPE_GRAPHICS	A graphics-related system call.

Function Documentation

◆ drsys_cur_syscall()

DR_EXPORT drmf_status_t drsys_cur_syscall	(	void *	drcontext,
		DR_PARAM_OUT drsys_syscall_t **	syscall
	)

Retrieves the system call handle for the current in-progress system call. The handle is only valid through the end of the post-system-call event for the system call.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[out]	syscall	The system call handle.

Returns: success code.

◆ drsys_cur_syscall_result()

DR_EXPORT drmf_status_t drsys_cur_syscall_result	(	void *	drcontext,
		DR_PARAM_OUT bool *	success,
		DR_PARAM_OUT uint64 *	value,
		DR_PARAM_OUT uint *	error_code
	)

Returns whether the just-completed system call succeeded along with the value and error code returned. Must be called from a post-system-call event.

This routine distinguishes itself from dr_syscall_get_result_ex() by providing accurate results for all system calls, in particular including Windows win32k.sys graphical (NtGdi) and user (NtUser) system calls. It also knows which system calls return 64-bit results, eliminating the need for the caller to specifically request the top 32 bits in such cases.

On Windows, system calls that return an error code like STATUS_BUFFER_TOO_SMALL OUT but that still write an output param are considered to have succeeded.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[out]	success	Whether the system call succeeded. This parameter is optional and may be NULL.
[out]	value	The value returned. This parameter is optional and may be NULL.
[out]	error_code	If the system call failed, this holds the error code returned by the kernel, normalized to a positive value (i.e., on Linux it is negated from the raw value returned by the kernel). If the system call succeeded, *error_code is set to 0. This parameter is optional and may be NULL.

Returns: success code.

◆ drsys_exit()

DR_EXPORT drmf_status_t drsys_exit ( void )

Cleans up the Dr. Syscall extension.

◆ drsys_filter_all_syscalls()

DR_EXPORT drmf_status_t drsys_filter_all_syscalls ( void )

Instructs Dr. Syscall that all system calls may be queried and must be tracked. In particular, Dr. Syscall only records pre-system call arguments for system calls that are filtered.

Returns: success code.

◆ drsys_filter_syscall()

DR_EXPORT drmf_status_t drsys_filter_syscall ( drsys_sysnum_t sysnum )

Instructs Dr. Syscall that this system call will be queried and must be tracked. In particular, Dr. Syscall only records pre-system call arguments for system calls that are filtered.

Parameters

[in] sysnum The system call number to track.

Returns: success code.

◆ drsys_find_sysnum_libs()

DR_EXPORT drmf_status_t drsys_find_sysnum_libs	(	DR_PARAM_OUT char **	sysnum_lib_paths,
		DR_PARAM_INOUT size_t *	num_sysnum_libs
	)

Locates the system libraries that contain system calls for the current operating system for the purpose of passing them to drsys_generate_sysnum_file(). Returns an array of paths. The caller must set the capacity of the array in num_sysnum_libs and allocate at least MAXIMUM_PATH bytes for each entry in the array. If the array length is too small, this function returns DRMF_ERROR_INVALID_SIZE and sets num_sysnum_libs to the size needed. On success, returns DRMF_SUCCESS and the library count in num_sysnum_libs.

Parameters

[out]	sysnum_lib_paths	Pointer to an array of length `num_sysnum_libs` which will hold the paths of the libraries on success.
[in,out]	num_sysnum_libs	The caller must set this to the capacity of `sysnum_lib_paths` on entry. On success this will hold the number of paths written to the array. When returning DRMF_ERROR_INVALID_SIZE this will hold the required size of the array.

Note: Windows-only.

◆ drsys_generate_sysnum_file()

DR_EXPORT drmf_status_t drsys_generate_sysnum_file	(	void *	drcontext,
		const char **	sysnum_lib_paths,
		size_t	num_sysnum_libs,
		const char *	outfile,
		const char *	cache_dir
	)

Writes out a text file that contains system call numbers for the operating system whose system libraries are in sysnum_lib_paths with a count of num_sysnum_libs. Typically this list will be obtained for the current operating system from drsys_find_sysnum_libs(). The text file is written to outfile in the format expected by the sysnum_file field of drsys_options_t.

To accomplish this, this function requires debug symbols for each of the libraries. It attempts to retrieve the symbols over the network if they are not found in the cache_dir or _NT_SYMBOL_PATH used by dbghelp.dll through the drsyms extension.

Parameters

[in]	drcontext	The current DynamoRIO thread context or standalone context.
[in]	sysnum_lib_paths	Pointer to an array of length `num_sysnum_libs` which holds the paths of the system libraries from which system call numbers should be extracted.
[in]	num_sysnum_libs	The length of the `sysnum_lib_paths` array.
[in]	outfile	The name of the output text file to be written.
[in]	cache_dir	The path where retrieved symbol data should be cached (and searched if already retrieved).

Note: Windows-only.

◆ drsys_get_mcontext()

DR_EXPORT drmf_status_t drsys_get_mcontext	(	void *	drcontext,
		DR_PARAM_OUT dr_mcontext_t **	mc
	)

Identifies the machine context of the application at the point of the current in-progress system call. The data is cached in the pre-syscall event only for those system calls that are filtered via drsys_filter_syscall() drsys_filter_all_syscalls(). Must be called from a system call pre- or post-event.

This is a copy of the machine context, for convenience. It should not be modified. To change the context, or to change system call parameters or return value, the client must use a separate system call event that is ordered prior to DRMGR_PRIORITY_PRESYS_DRSYS or DRMGR_PRIORITY_POSTSYS_DRSYS.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[out]	mc	The cached machine context.

Returns: success code.

◆ drsys_handle_is_current_process()

DR_EXPORT drmf_status_t drsys_handle_is_current_process	(	HANDLE	h,
		bool *	current
	)

Identifies whether the given process handle refers to the current process.

Parameters

[in]	h	The handle to query.
[out]	current	Whether the handle refers to the current process.

Returns: success code.

◆ drsys_init()

DR_EXPORT drmf_status_t drsys_init	(	client_id_t	client_id,
		drsys_options_t *	options
	)

Initializes the Dr. Syscall extension. Must be called prior to any of the other routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drsys_exit().

Parameters

[in]	client_id	The id of the client using drsys, as passed to dr_init().
[in]	options	Allows changing the default behavior of Dr. Syscall.

Returns: success code. The warning code DRMF_WARNING_UNSUPPORTED_KERNEL indicates that initialization completed but that false positives are a risk due to missing information.

◆ drsys_iterate_arg_types()

DR_EXPORT drmf_status_t drsys_iterate_arg_types	(	drsys_syscall_t *	syscall,
		drsys_iter_cb_t	cb,
		void *	user_data
	)

Statically iterates over all system call parameters for the given system call. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

Only the top-level types are enumerated (i.e., fields of structures are not recursively followed). As this is a static iteration, only the types are known and not any values. The return value is included at the end of the iteration, with a drsys_arg_t.ordinal value of -1.

Note: Some system calls have varying return types, which depend on the parameters passed in (e.g., on Windows, NtGdiPolyPolyDraw returns either a BOOL or an HRGN). The dynamic argument iterator drsys_iterate_args can be used to identify the precise return type for a particular instance.

Parameters

[in]	syscall	The handle for the system call to query.
[in]	cb	The callback to invoke for each system call parameter. The callback's return value indicates whether to continue the iteration.
[in]	user_data	A custom parameter passed to `cb`.

Returns: success code.

◆ drsys_iterate_args()

DR_EXPORT drmf_status_t drsys_iterate_args	(	void *	drcontext,
		drsys_iter_cb_t	cb,
		void *	user_data
	)

Dynamically iterates over all system call parameters for the current in-progress system call. Only the top-level types are enumerated (i.e., fields of structures are not recursively followed). The return value is included. Must be called from a system call pre- or post-event.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[in]	cb	The callback to invoke for each system call parameter. The callback's return value indicates whether to continue the iteration.
[in]	user_data	A custom parameter passed to `cb`.

Returns: success code.

◆ drsys_iterate_memargs()

DR_EXPORT drmf_status_t drsys_iterate_memargs	(	void *	drcontext,
		drsys_iter_cb_t	cb,
		void *	user_data
	)

Dynamically iterates over all memory regions read or written by the current in-progress system call. Does descend into fields of data structures.

Must be called from a system call pre- or post-event. If this is called from a post-system call event, it must also be called from the pre-system call event, as some information required for post-system call values is stored during pre-system call iteration.

In pre-syscall, for OUT parameters, may treat a region containing padding between structure fields as a single region. Otherwise, splits up any region with padding into multiple iteration steps.

For unknown syscalls, may call cb for each byte of memory even for adjacent bytes, as it uses a heuristic to try and detect written memory.

Does NOT iterate over the primary parameter values themselves, even if they are located in memory: use drsys_iterate_args() for that.

If unable to read the value of a parameter, will skip potential memory regions.

Some memory regions may overlap each other. This occurs when the full capacity of a structure is passed to cb with a mode of DRSYS_PARAM_BOUNDS and the fields of the structure are subsequently enumerated separately.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[in]	cb	The callback to invoke for each memory region. The callback's return value indicates whether to continue the iteration.
[in]	user_data	A custom parameter passed to `cb`.

Returns: success code.

◆ drsys_iterate_syscalls()

DR_EXPORT drmf_status_t drsys_iterate_syscalls	(	bool()(drsys_sysnum_t sysnum, drsys_syscall_t syscall, void *user_data)	cb,
		void *	user_data
	)

Iterates over all system call numbers and calls the given callback for each one. The argument types of each system call can then be enumerated by calling drsys_iterate_arg_types() and passing the given system call handle syscall.

This will enumerate all system calls even if the libraries containing their wrappers have not yet been loaded. System calls whose parameter details are unknown are included (see drsys_syscall_is_known()).

Parameters

[in]	cb	The callback to invoke for each system call number. The callback's return value indicates whether to continue the iteration.
[in]	user_data	A custom parameter passed to `cb`.

Returns: success code.

◆ drsys_name_to_syscall()

DR_EXPORT drmf_status_t drsys_name_to_syscall	(	const char *	name,
		DR_PARAM_OUT drsys_syscall_t **	syscall
	)

Given a system call name, retrieves a handle to the system call to be used for further queries. The handle is valid until drsys_exit() is called. On Windows, multiple versions of the name are accepted. For ntoskrnl system calls, the Nt or Zw varieties are supported. For secondary system calls like NtUserCallOneParam.RELEASEDC, the full name as well as just the secondary name (RELEASEDC) are accepted. The lookup is case-insensitive on Windows. This can be called in dr_init() for all system calls, even if the libraries containing their wrappers have not yet been loaded.

Parameters

[in]	name	The system call name to look up.
[out]	syscall	The system call handle.

Returns: success code.

◆ drsys_number_to_syscall()

DR_EXPORT drmf_status_t drsys_number_to_syscall	(	drsys_sysnum_t	sysnum,
		DR_PARAM_OUT drsys_syscall_t **	syscall
	)

Given a system call number, retrieves a handle to the system call to be used for further queries. The handle is valid until drsys_exit() is called. This can be called in dr_init() for all system calls, even if the libraries containing their wrappers have not yet been loaded.

Parameters

[in]	sysnum	The system call number to look up.
[out]	syscall	The system call handle.

Returns: success code.

◆ drsys_pre_syscall_arg()

DR_EXPORT drmf_status_t drsys_pre_syscall_arg	(	void *	drcontext,
		uint	argnum,
		DR_PARAM_OUT ptr_uint_t *	value
	)

Identifies the value of a system call argument as passed to the current in-progress system call. The value is cached in the pre-syscall event only for those system calls that are filtered via drsys_filter_syscall() or drsys_filter_all_syscalls(). Must be called from a system call pre- or post-event.

Deprecated:: For 32-bit applications, some platforms (namely MacOS) support 64-bit arguments. For such cases, the value returned here will hold only the bottom 32 bits of the value. We recommend using drsys_pre_syscall_arg64() instead for cross-platform code.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[in]	argnum	The ordinal of the parameter to query.
[out]	value	The value of the parameter.

Returns: success code.

Note: On 32-bit MacOS, the ordinal differs from that used in dr_syscall_get_param(), as dr_syscall_get_param() splits 64-bit arguments into two pieces. Here, 64-bit arguments occupy just one slot.

◆ drsys_pre_syscall_arg64()

DR_EXPORT drmf_status_t drsys_pre_syscall_arg64	(	void *	drcontext,
		uint	argnum,
		DR_PARAM_OUT uint64 *	value
	)

Identifies the value of a system call argument as passed to the current in-progress system call. The value is cached in the pre-syscall event only for those system calls that are filtered via drsys_filter_syscall() or drsys_filter_all_syscalls(). Must be called from a system call pre- or post-event.

Parameters

[in]	drcontext	The current DynamoRIO thread context.
[in]	argnum	The ordinal of the parameter to query.
[out]	value	The value of the parameter.

Returns: success code.

Note: On 32-bit MacOS, the ordinal differs from that used in dr_syscall_get_param(), as dr_syscall_get_param() splits 64-bit arguments into two pieces. Here, 64-bit arguments occupy just one slot.

◆ drsys_syscall_gateway()

DR_EXPORT drmf_status_t drsys_syscall_gateway ( drsys_gateway_t * method )

Returns the primary method used to invoke the kernel for a system call. Prior to the first system call invoked by the application, this will return DRSYS_GATEWAY_UNKNOWN. Although this is the typical method, other methods may be used within the same application (e.g., on Linux, even when DRSYS_GATEWAY_SYSENTER or DRSYS_GATEWAY_SYSCALL is used for most system calls, DRSYS_GATEWAY_INT is still used for certain stack-sensitive or multi-argument system calls).

Parameters

[out] method The gateway method in use by the application.

Returns: whether successful.

◆ drsys_syscall_is_known()

DR_EXPORT drmf_status_t drsys_syscall_is_known	(	drsys_syscall_t *	syscall,
		DR_PARAM_OUT bool *	known
	)

Identifies whether the system call details for the given syscall are known. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

Parameters

[in]	syscall	The handle for the system call to query.
[out]	known	Whether known.

Returns: success code.

◆ drsys_syscall_name()

DR_EXPORT drmf_status_t drsys_syscall_name	(	drsys_syscall_t *	syscall,
		DR_PARAM_OUT const char **	name
	)

Given a system call handle, retrieves the canonical system call name. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

Parameters

[in]	syscall	The handle for the system call to query.
[out]	name	The system call name.

Returns: success code.

◆ drsys_syscall_number()

DR_EXPORT drmf_status_t drsys_syscall_number	(	drsys_syscall_t *	syscall,
		DR_PARAM_OUT drsys_sysnum_t *	sysnum
	)

Given a system call handle, retrieves the system call number. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

Parameters

[in]	syscall	The handle for the system call to query.
[out]	sysnum	The system call number.

Returns: success code.

◆ drsys_syscall_return_type()

DR_EXPORT drmf_status_t drsys_syscall_return_type	(	drsys_syscall_t *	syscall,
		DR_PARAM_OUT drsys_param_type_t *	type
	)

Identifies the type of the return value for the specified system call. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

Note: Some system calls have varying return types, which depend on the parameters passed in (e.g., on Windows, NtGdiPolyPolyDraw returns either a BOOL or an HRGN). The dynamic argument iterator drsys_iterate_args can be used to identify the precise return type for a particular instance.

Parameters

[in]	syscall	The handle for the system call to query.
[out]	type	The system call return type.

Returns: success code.

◆ drsys_syscall_succeeded()

DR_EXPORT drmf_status_t drsys_syscall_succeeded	(	drsys_syscall_t *	syscall,
		reg_t	result,
		DR_PARAM_OUT bool *	success
	)

For Windows or Linux, identifies whether the given value is a successful return value for the given system call.

Warning: On MacOS, this routine always fails with DRMF_ERROR_FEATURE_NOT_AVAILABLE, as success depends on the condition codes and not on the value itself. Furthermore, the value can be 64 bits for a 32-bit application. Use drsys_cur_syscall_result() instead.

The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

The system call result can be obtained from dr_syscall_get_result().

On Windows, system calls that return an error code like STATUS_BUFFER_TOO_SMALL OUT but that still write an output param are considered to have succeeded.

Parameters

[in]	syscall	The handle for the system call to query.
[in]	result	The system call return value.
[out]	success	Whether the value indicates success.

Returns: success code.

◆ drsys_syscall_type()

DR_EXPORT drmf_status_t drsys_syscall_type	(	drsys_syscall_t *	syscall,
		DR_PARAM_OUT drsys_syscall_type_t *	type
	)

Identifies the type of system call. The system call handle can be obtained from drsys_cur_syscall(), drsys_iterate_syscalls(), drsys_name_to_syscall(), drsys_number_to_syscall(), or drsys_arg_t.syscall.

Parameters

[in]	syscall	The handle for the system call to query.
[out]	type	The system call type.

Returns: success code.

◆ drsys_sysnums_equal()

static bool drsys_sysnums_equal	(	drsys_sysnum_t *	num1,
		drsys_sysnum_t *	num2
	)

inlinestatic

Returns whether the two system call numbers are equal.

Parameters

[in]	num1	The first number to compare.
[in]	num2	The second number to compare.

Returns: whether equal.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DRMGR_PRIORITY_NAME_DRSYS

◆ DRMGR_PRIORITY_NAME_DRSYS_LAST

◆ DRSYS_SYSNUM_FILE_FOOTER

◆ DRSYS_SYSNUM_FILE_HEADER

◆ DRSYS_SYSNUM_FILE_VERSION

Typedef Documentation

◆ drsys_arg_t

◆ drsys_iter_cb_t

◆ drsys_options_t

◆ drsys_syscall_t

◆ drsys_sysnum_t

Enumeration Type Documentation

◆ anonymous enum

◆ drsys_gateway_t

◆ drsys_param_mode_t

◆ drsys_param_type_t

◆ drsys_syscall_type_t

Function Documentation

◆ drsys_cur_syscall()

◆ drsys_cur_syscall_result()

◆ drsys_exit()

◆ drsys_filter_all_syscalls()

◆ drsys_filter_syscall()

◆ drsys_find_sysnum_libs()

◆ drsys_generate_sysnum_file()

◆ drsys_get_mcontext()

◆ drsys_handle_is_current_process()

◆ drsys_init()

◆ drsys_iterate_arg_types()

◆ drsys_iterate_args()

◆ drsys_iterate_memargs()

◆ drsys_iterate_syscalls()

◆ drsys_name_to_syscall()

◆ drsys_number_to_syscall()

◆ drsys_pre_syscall_arg()

◆ drsys_pre_syscall_arg64()

◆ drsys_syscall_gateway()

◆ drsys_syscall_is_known()

◆ drsys_syscall_name()

◆ drsys_syscall_number()

◆ drsys_syscall_return_type()

◆ drsys_syscall_succeeded()

◆ drsys_syscall_type()

◆ drsys_sysnums_equal()