GtSyscallFunc ()

void *
(*GtSyscallFunc) (GtGuestState *state,
                  gt_pid_t pid,
                  gt_tid_t tid,
                  void *user_data);

Specifies one of the two types of functions passed to gt_loop_set_cb(). The guestrace event loop invokes this callback each time a program running on the guest invokes the corresponding system call. Implementations can optionally return a pointer which the guestrace event loop will later pass to the corresponding GtSysretFunc after the system call returns.

GtSysretFunc ()

void
(*GtSysretFunc) (GtGuestState *state,
                 gt_pid_t pid,
                 gt_tid_t tid,
                 void *user_data);

Specifies one of the two types of functions passed to gt_loop_set_cb(). The guestrace event loop invokes this callback each time a system call on the guest returns control to a program. It is the responsibility of each GtSysretFunc implementation to free user_data if the corresponding GtSyscallFunc returned a pointer to a dynamically-allocated object.

gt_loop_new ()

GtLoop *
gt_loop_new (const char *guest_name);

Creates a new GtLoop structure.

gt_loop_get_ostype ()

GtOSType
gt_loop_get_ostype (GtLoop *loop);

gt_loop_get_guest_name ()

const char *
gt_loop_get_guest_name (GtLoop *loop);

gt_loop_get_vmi_instance ()

vmi_instance_t
gt_loop_get_vmi_instance (GtLoop *loop);

Returns the vmi_instance_t associated with loop . Refer to the libvmi documentation for a description of vmi_instance_t.

gt_loop_set_cb ()

gboolean
gt_loop_set_cb (GtLoop *loop,
                const char *kernel_func,
                GtSyscallFunc syscall_cb,
                GtSysretFunc sysret_cb,
                void *user_data);

Sets the callback functions associated with kernel_func . Each time the guest kernel calls kernel_func to process a system call, the loop will invoke syscall_cb . When kernel_func returns, the loop will invoke sysret_cb . The loop passes user_data to syscall_cb , and it passes the return value from syscall_cb to sysret_cb .

gt_loop_set_cbs ()

int
gt_loop_set_cbs (GtLoop *loop,
                 const GtCallbackRegistry callbacks[]);

A convenience function which repeatedly invokes gt_loop_set_cb for each callback defined in syscalls . The syscalls array must be terminated with a GtCallbackRegistry with each field set to NULL.

gt_loop_get_syscall_count ()

unsigned long
gt_loop_get_syscall_count (GtLoop *loop);

gt_loop_add_watch ()

guint
gt_loop_add_watch (GIOChannel *channel,
                   GIOCondition condition,
                   GIOFunc func,
                   gpointer user_data);

Adds a GIOChannel to the loop. The loop will call func each time one of the conditions specified in condition exists on channel , and it will pass user_data to func . This is useful for adding keyboard and other handlers to the loop.

gt_guest_get_register ()

gt_reg_t
gt_guest_get_register (GtGuestState *state,
                       gt_reg_name_t name);

Returns the value of the named register from the guest state.

gt_guest_get_bytes ()

size_t
gt_guest_get_bytes (GtGuestState *state,
                    gt_addr_t vaddr,
                    gt_pid_t pid,
                    void *buf,
                    size_t count);

Copies a sequence of up to count bytes which starts at vaddr into the memory starting at buf . Returns the number of bytes copied.

gt_guest_get_string ()

char *
gt_guest_get_string (GtGuestState *state,
                     gt_addr_t vaddr,
                     gt_pid_t pid);

Returns the NULL-terminated string which starts at vaddr or NULL on error. The caller must free the returned string.

gt_guest_get_argv ()

char **
gt_guest_get_argv (GtGuestState *state,
                   gt_addr_t vaddr,
                   gt_pid_t pid);

Returns the NULL-terminated argv-style array which starts at vaddr or NULL on error. Each item in the array is a string. The caller must free the array and each string in the array.

gt_guest_get_uint32 ()

status_t
gt_guest_get_uint32 (GtGuestState *state,
                     gt_addr_t vaddr,
                     gt_pid_t pid,
                     uint32_t *value);

Copies the 32-bit value at vaddr in the address space of pid to the address value .

Returns VMI_SUCCESS or some error code.

gt_guest_get_vmi_instance ()

vmi_instance_t
gt_guest_get_vmi_instance (GtGuestState *state);

Returns the vmi_instance_t associated with state . Refer to the libvmi documentation for a description of vmi_instance_t.

gt_guest_get_vmi_event ()

vmi_event_t *
gt_guest_get_vmi_event (GtGuestState *state);

Returns the vmi_event_t associated with state . Refer to the libvmi documentation for a description of vmi_event_t.

gt_guest_get_process_name ()

char *
gt_guest_get_process_name (GtGuestState *state);

Returns the process name associated with state . The caller must free the returned string.

gt_guest_get_parent_pid ()

gt_pid_t
gt_guest_get_parent_pid (GtGuestState *state,
                         gt_pid_t pid,
                         gboolean *is_userspace);

Returns the PID of the parent of the process associated with state .

gt_guest_hijack_return ()

void
gt_guest_hijack_return (GtGuestState *state,
                        reg_t retval);

This function manipulates the guest to hijack the current system call such that the system call does not execute and instead immediately returns retval . This function can only be called from within a GtSyscallFunc.

gt_guest_drop_return_breakpoint ()

void
gt_guest_drop_return_breakpoint (GtGuestState *state);

Drop the return breakpoint associated with this system call. Applications should call this in special cases, such as with clone/CLONE_VM on Linux. This function can only be called from within a GtSyscallFunc.

gt_guest_clear_return_state ()

void
gt_guest_clear_return_state (GtGuestState *state);

Free this and any other states associated with the process. Applications should call this when they know the instrumented function will never return, such as with pspexitthread on Windows. This function can only be called from within a GtSyscallFunc.

gt_loop_run ()

void
gt_loop_run (GtLoop *loop);

Uses libvmi to complete the preparations necessary to trace a guest's system calls. Runs loop until gt_loop_quit() is called on loop .

gt_loop_quit ()

void
gt_loop_quit (GtLoop *loop);

Stops loop from running. Any calls to gt_loop_run() for the loop will return. This removes any modifications to the guest's memory and allows the guest to run without instrumentation.

gt_loop_free ()

void
gt_loop_free (GtLoop *loop);

Free loop and its associated memory. If the loop is currently running, then gt_loop_quit() must first terminate the loop and remove the guest instrumentation.

gt_loop_jmp_past_cb ()

void
gt_loop_jmp_past_cb (GtLoop *loop);

Skip over the syscall/sysret handler, usually to gracefully exit after receiving a fatal signal. A typical use is to call gt_loop_quit() and gt_loop_jmp_past_cb() from a program's SIGSEGV handler.

gt_reg_name_t

typedef int gt_reg_name_t;

The gt_reg_name_t enum contains the valid names of the registers found on the guest.

gt_addr_t

typedef addr_t    gt_addr_t;

A guest virtual memory address.

gt_pid_t

typedef vmi_pid_t gt_pid_t;

The unique identifier for a guest process.

gt_tid_t

typedef addr_t    gt_tid_t;

The unique identifier for a guest thread. An identifier which serves to correlate between calls and returns at thread granularity.

gt_reg_t

typedef reg_t     gt_reg_t;

The value of some guest register.

GtCallbackRegistry

typedef struct {
} GtCallbackRegistry;

Full callback definition for use with gt_loop_set_cbs().

enum GtOSType

Enum values which specify the operating system running on the guest.

GtGuestState

typedef struct {
} GtGuestState;

The GtGuestState struct is an opaque data type representing the state of the instrumented guest.

GtLoop

typedef struct {
} GtLoop;

The GtLoop struct is an opaque data type representing the main event loop of a guestrace application.