Dr. Memory
drsyscall.h File Reference

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

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 ,
  DRSYS_TYPE_LAST_PLUS_ONE ,
  DRSYS_TYPE_LAST = DRSYS_TYPE_LAST_PLUS_ONE - 1
}
 
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, OUT drsys_syscall_t **syscall)
 
DR_EXPORT drmf_status_t drsys_number_to_syscall (drsys_sysnum_t sysnum, OUT drsys_syscall_t **syscall)
 
DR_EXPORT drmf_status_t drsys_syscall_name (drsys_syscall_t *syscall, OUT const char **name)
 
DR_EXPORT drmf_status_t drsys_syscall_number (drsys_syscall_t *syscall, OUT drsys_sysnum_t *sysnum)
 
DR_EXPORT drmf_status_t drsys_syscall_type (drsys_syscall_t *syscall, OUT drsys_syscall_type_t *type)
 
DR_EXPORT drmf_status_t drsys_syscall_is_known (drsys_syscall_t *syscall, OUT bool *known)
 
DR_EXPORT drmf_status_t drsys_syscall_succeeded (drsys_syscall_t *syscall, reg_t result, OUT bool *success)
 
DR_EXPORT drmf_status_t drsys_syscall_return_type (drsys_syscall_t *syscall, 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, OUT drsys_syscall_t **syscall)
 
DR_EXPORT drmf_status_t drsys_cur_syscall_result (void *drcontext, OUT bool *success, OUT uint64 *value, OUT uint *error_code)
 
DR_EXPORT drmf_status_t drsys_pre_syscall_arg (void *drcontext, uint argnum, OUT ptr_uint_t *value)
 
DR_EXPORT drmf_status_t drsys_pre_syscall_arg64 (void *drcontext, uint argnum, OUT uint64 *value)
 
DR_EXPORT drmf_status_t drsys_get_mcontext (void *drcontext, 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 (OUT char **sysnum_lib_paths, 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

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

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

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

◆ 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

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

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,
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]drcontextThe current DynamoRIO thread context.
[out]syscallThe system call handle.
Returns
success code.

◆ drsys_cur_syscall_result()

DR_EXPORT drmf_status_t drsys_cur_syscall_result ( void *  drcontext,
OUT bool *  success,
OUT uint64 *  value,
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]drcontextThe current DynamoRIO thread context.
[out]successWhether the system call succeeded. This parameter is optional and may be NULL.
[out]valueThe value returned. This parameter is optional and may be NULL.
[out]error_codeIf 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]sysnumThe system call number to track.
Returns
success code.

◆ drsys_find_sysnum_libs()

DR_EXPORT drmf_status_t drsys_find_sysnum_libs ( OUT char **  sysnum_lib_paths,
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_pathsPointer to an array of length num_sysnum_libs which will hold the paths of the libraries on success.
[in,out]num_sysnum_libsThe 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]drcontextThe current DynamoRIO thread context or standalone context.
[in]sysnum_lib_pathsPointer 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_libsThe length of the sysnum_lib_paths array.
[in]outfileThe name of the output text file to be written.
[in]cache_dirThe 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,
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]drcontextThe current DynamoRIO thread context.
[out]mcThe 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]hThe handle to query.
[out]currentWhether 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_idThe id of the client using drsys, as passed to dr_init().
[in]optionsAllows 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]syscallThe handle for the system call to query.
[in]cbThe callback to invoke for each system call parameter. The callback's return value indicates whether to continue the iteration.
[in]user_dataA 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]drcontextThe current DynamoRIO thread context.
[in]cbThe callback to invoke for each system call parameter. The callback's return value indicates whether to continue the iteration.
[in]user_dataA 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]drcontextThe current DynamoRIO thread context.
[in]cbThe callback to invoke for each memory region. The callback's return value indicates whether to continue the iteration.
[in]user_dataA 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]cbThe callback to invoke for each system call number. The callback's return value indicates whether to continue the iteration.
[in]user_dataA custom parameter passed to cb.
Returns
success code.

◆ drsys_name_to_syscall()

DR_EXPORT drmf_status_t drsys_name_to_syscall ( const char *  name,
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]nameThe system call name to look up.
[out]syscallThe system call handle.
Returns
success code.

◆ drsys_number_to_syscall()

DR_EXPORT drmf_status_t drsys_number_to_syscall ( drsys_sysnum_t  sysnum,
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]sysnumThe system call number to look up.
[out]syscallThe system call handle.
Returns
success code.

◆ drsys_pre_syscall_arg()

DR_EXPORT drmf_status_t drsys_pre_syscall_arg ( void *  drcontext,
uint  argnum,
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]drcontextThe current DynamoRIO thread context.
[in]argnumThe ordinal of the parameter to query.
[out]valueThe 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,
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]drcontextThe current DynamoRIO thread context.
[in]argnumThe ordinal of the parameter to query.
[out]valueThe 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]methodThe 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,
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]syscallThe handle for the system call to query.
[out]knownWhether known.
Returns
success code.

◆ drsys_syscall_name()

DR_EXPORT drmf_status_t drsys_syscall_name ( drsys_syscall_t syscall,
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]syscallThe handle for the system call to query.
[out]nameThe system call name.
Returns
success code.

◆ drsys_syscall_number()

DR_EXPORT drmf_status_t drsys_syscall_number ( drsys_syscall_t syscall,
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]syscallThe handle for the system call to query.
[out]sysnumThe system call number.
Returns
success code.

◆ drsys_syscall_return_type()

DR_EXPORT drmf_status_t drsys_syscall_return_type ( drsys_syscall_t syscall,
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]syscallThe handle for the system call to query.
[out]typeThe 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,
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]syscallThe handle for the system call to query.
[in]resultThe system call return value.
[out]successWhether the value indicates success.
Returns
success code.

◆ drsys_syscall_type()

DR_EXPORT drmf_status_t drsys_syscall_type ( drsys_syscall_t syscall,
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]syscallThe handle for the system call to query.
[out]typeThe 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]num1The first number to compare.
[in]num2The second number to compare.
Returns
whether equal.