Skip to content

API Reference

Jump to bottom
xwings edited this page Jul 6, 2025 · 5 revisions

Qiling API Reference

This document provides a high-level overview of the main Qiling Framework API. For detailed information on specific functions, parameters, and classes, please refer to the source code itself, which is the most up-to-date reference.

The Qiling Object

The Qiling object is the central hub for all emulation tasks. It is instantiated to create a new emulation environment.

class qiling.Qiling(argv, rootfs, ostype=None, archtype=None, verbose=QL_VERBOSE.OFF, ...)

Key Attributes:

  • ql.arch: Access to architecture-specific properties and helpers.
  • ql.os: Access to the operating system emulation layer.
  • ql.loader: Access to the file loader, containing information about the loaded binary.
  • ql.mem: The memory manager.
  • ql.reg: The CPU register manager.
  • ql.fs: The virtual filesystem manager.
  • ql.debugger: The debugger interface.

Key Methods:

  • ql.run(begin=None, end=None, timeout=0, count=0): Starts or resumes emulation.
  • ql.save(): Saves a snapshot of the current machine state.
  • ql.restore(): Restores the last saved snapshot.
  • ql.hook_address(callback, address): Hooks a specific memory address.
  • ql.hook_code(callback, begin=1, end=0): Hooks a range of code for instruction-level tracing.

Memory (ql.mem)

Manages the emulated memory space.

  • ql.mem.read(address, size): Reads size bytes from address.
  • ql.mem.write(address, data): Writes data (bytes) to address.
  • ql.mem.string(address): Reads a null-terminated string from address.
  • ql.mem.alloc(size): Allocates a new memory region of size bytes.
  • ql.mem.free(address): Frees a previously allocated memory region.
  • ql.mem.get_map(): Returns the entire memory map of the process.
  • ql.mem.is_mapped(address, size): Checks if a memory range is mapped.

Registers (ql.reg)

Provides access to CPU registers.

  • ql.reg.<register_name>: Read from a register (e.g., ql.reg.eax, ql.reg.rdi).
  • ql.reg.<register_name> = value: Write to a register (e.g., ql.reg.eax = 0x123).
  • ql.reg.read(reg_id): Read from a register using its Unicorn ID.
  • ql.reg.write(reg_id, value): Write to a register using its Unicorn ID.

Operating System (ql.os)

Manages OS-level emulation, including syscalls and APIs.

  • ql.os.set_syscall(syscall_name, callback): Overrides a syscall handler.
  • ql.os.set_api(api_name, callback, dll_name=None): Hooks a Windows API call.
  • ql.os.set_env(key, value): Sets an environment variable.
  • ql.os.registry: Access to the virtual Windows Registry.

Virtual Filesystem (ql.fs)

Manages the virtual filesystem.

  • ql.fs.open(path, flags): Opens a virtual file.
  • ql.fs.read(fd, size): Reads from a file descriptor.
  • ql.fs.write(path_or_fd, data): Writes data to a file path or descriptor.
  • ql.fs.mkdir(path, mode): Creates a directory.
  • ql.fs.exists(path): Checks if a file or directory exists.
  • ql.add_fs_mapper(host_path, emu_path): Maps a host directory into the VFS.

Further Exploration

This reference is not exhaustive. The Qiling codebase is well-structured and serves as the ultimate source of truth. We encourage you to explore the following directories in the source code for more details:

  • qiling/core.py: The main Qiling class.
  • qiling/os/: The OS emulation layer, with subdirectories for each supported OS.
  • qiling/arch/: Architecture-specific code.
  • qiling/loader/: The file format loaders.
Clone this wiki locally