Dr. Memory |

Data Structures | Macros | Typedefs | Enumerations | Functions
drsyscall.h File Reference

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, DRMGR_PRIORITY_EXCPT_UMBRA = -100, DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ = -150, DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE = 150, DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE = -150 }
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, 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

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().
DRMGR_PRIORITY_EXCPT_UMBRA | Priority of the Umbra signal/exception handling event. This event must take place before any user of drsyscall in order to allocate shadow memory if necessary.
DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ | Priority of the drsymcache module load event action that checks for a symbol cache file and reads it in. This event must occur before any drsymcache API usage in module load events of users of drsymcache.
DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE | Priority of the drsymcache module load event action that saves the current symbol cache from memory to disk.
DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE | Priority of the drsymcache module unload event action that saves the current symbol cache from memory to disk and then frees the in-memory cache data structures. This event must occur after any drsymcache API usage in module unload events of users of drsymcache.

## ◆ 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,
|  | 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,
|  | 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] | 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 | ( | 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_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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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
| ) |  |
| inline static

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.