### Make AppImage Executable and Run PINCE

Source: https://github.com/korcankaraokcu/pince/blob/master/README.md

This snippet shows how to make the downloaded AppImage executable and then run it. It's a straightforward process for end-users to get started with PINCE.

```bash
chmod +x PINCE-x86_64.AppImage
sudo -E ./PINCE-x86_64.AppImage
```

--------------------------------

### Clone PINCE Repository and Install Development Environment

Source: https://github.com/korcankaraokcu/pince/blob/master/README.md

This snippet outlines the steps for developers to clone the PINCE repository and set up a virtual environment for local development. It ensures all necessary dependencies are installed.

```bash
git clone --recursive https://github.com/korcankaraokcu/PINCE
sh PINCE/install.sh
```

--------------------------------

### Process Utilities for Discovery and Inspection

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Provides utility functions for discovering running processes and inspecting their memory regions. Functions include listing all processes, searching by name, getting process names by PID, and retrieving detailed memory region information, with options to filter by permissions.

```python
from libpince import utils

# Get list of all running processes
processes = utils.get_process_list()
for pid, user, name in processes[:10]:
    print(f"PID: {pid}, User: {user}, Name: {name}")

# Search for processes by name
matches = utils.search_processes("firefox")
for pid, user, name in matches:
    print(f"Found: {pid} - {name}")

# Get process name by PID
name = utils.get_process_name(12345)

# Get memory regions of a process
regions = utils.get_regions(12345)
for start, end, perms, offset, device, inode, path in regions:
    print(f"{start}-{end} {perms} {path}")

# Filter regions by permission
executable_regions = utils.filter_regions(
    pid=12345,
    attribute="permissions",
    regex="x",  # Contains execute permission
    case_sensitive=True
)

# Get info about a specific address
info = utils.get_region_info(12345, 0x401000)
if info:
    print(f"Region: {hex(info.start)}-{hex(info.end)} {info.perms} {info.file_name}")
```

--------------------------------

### Examine GDB Expressions with Python

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Offers functions to evaluate GDB expressions and retrieve address and symbol information. It supports examining single expressions to get details like address and symbol, and also examining multiple expressions efficiently in a single call. Requires the 'libpince' library.

```python
from libpince import debugcore

# Examine a symbol
result = debugcore.examine_expression("malloc")
print(f"Full: {result.all}")
print(f"Address: {result.address}")
print(f"Symbol: {result.symbol}")

# Examine multiple expressions efficiently
expressions = ["main", "printf", "$rax", "$rsp+0x10"]
results = debugcore.examine_expressions(expressions)

for expr, result in zip(expressions, results):
    print(f"{expr} -> {result.address}")
```

--------------------------------

### Get Stack from Base Pointer (Python)

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Retrieves stack information starting from the base pointer (EBP/RBP). This function allows for a different perspective on stack traversal compared to the default method, useful for specific debugging scenarios.

```python
stack_from_bp = debugcore.get_stack_info(from_base_pointer=True)
```

--------------------------------

### Create and Debug New Process with libpince

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Launches a new process from a specified binary and attaches the debugger to it immediately. This allows for debugging from the very beginning of the program's execution. It supports passing command-line arguments and preloading shared libraries.

```python
from libpince import debugcore

# Create and attach to a new process
binary_path = "/usr/games/assaultcube"
args = "--windowed"
ld_preload = ""  # Optional .so file to preload

success = debugcore.create_process(binary_path, args, ld_preload)

if success:
    print(f"Process created, PID: {debugcore.currentpid}")
    # Continue execution to entry point
    debugcore.continue_inferior()
else:
    print("Failed to create process")
```

--------------------------------

### Using Library Function Names as GDB Expressions in PINCE

Source: https://github.com/korcankaraokcu/pince/wiki/GDB-Expressions

In PINCE's 'AddAddressManually' dialog, you can input common library function names. PINCE resolves these to their starting addresses and values, which can then be added to the address list.

```text
malloc
open
printf
scanf
```

--------------------------------

### libpince.debugcore.find_entry_point()

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Finds the entry point of the inferior process. Returns the entry point as a hexadecimal string or None if it fails.

```APIDOC
## GET libpince.debugcore.find_entry_point()

### Description
Finds the entry point of the inferior process.

### Method
GET

### Endpoint
/libpince.debugcore/find_entry_point

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **entry_point** (str) - The entry point as a hex string.
- **None** - If fails to find an entry point.

#### Response Example
```json
{
  "entry_point": "0x12345678"
}
```
OR
```json
{
  "entry_point": null
}
```
```

--------------------------------

### Get Current Stack Contents (Python)

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Fetches and displays the current stack contents of a process. It iterates through the returned stack information, printing the stack pointer, its hexadecimal value, and any associated pointer information for each entry.

```python
stack_info = debugcore.get_stack_info()
for stack_ptr, hex_value, pointer_info in stack_info:
    print(f"{stack_ptr}: {hex_value} {pointer_info}")
```

--------------------------------

### libPince Utility Functions

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

This section details various utility functions available in the libpince.utils module.

```APIDOC
## libpince.utils.aob_to_str(list_of_bytes, encoding='ascii', replace_unprintable=True)

### Description
Converts a given array of hex strings to a string.

### Method
`aob_to_str`

### Parameters
#### Arguments
- **list_of_bytes** (list) - Required - Must be returned from debugcore.hex_dump()
- **encoding** (str) - Optional - Default: 'ascii'. See documentation for standard encodings.
- **replace_unprintable** (bool) - Optional - Default: True. If True, replaces non-printable characters with a period (.).

### Returns
str: The string equivalent of the input byte array.

### libpince.utils.append_file_extension(string, extension)

### Description
Appends the given extension to the given string if it doesn’t already end with it.

### Method
`append_file_extension`

### Parameters
#### Arguments
- **string** (str) - Required - The string to append the extension to.
- **extension** (str) - Required - The extension to append (e.g., 'txt', 'log'). Do not include the dot.

### Returns
str: The original string with the extension appended if it was missing.

### libpince.utils.assemble(instructions, address, inferior_arch)

### Description
Assembles the given assembly instructions into bytes.

### Method
`assemble`

### Parameters
#### Arguments
- **instructions** (str) - Required - A string of instructions, separated by semicolons (;).
- **address** (int) - Required - The starting address for the assembly.
- **inferior_arch** (int) - Required - The architecture of the inferior process. Use values from `typedefs.INFERIOR_ARCH`.

### Returns
tuple: A tuple containing a list of assembled bytes (integers) and the instruction count. Returns None if an error occurs.

### libpince.utils.change_trace_status(pid, trace_status)

### Description
Changes the trace status for a given process ID.

### Method
`change_trace_status`

### Parameters
#### Arguments
- **pid** (int | str) - Required - The Process ID (PID) of the target process.
- **trace_status** (int) - Required - The new trace status. Use values from `typedefs.TRACE_STATUS`.

### Returns
None
```

--------------------------------

### libpince.debugcore Module Functions

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/modules.md

This section details the core functions available in the libpince.debugcore module for debugging operations.

```APIDOC
## libpince.debugcore Functions

### Description
Provides a comprehensive set of functions for debugging processes, including breakpoint management, memory inspection, process control, and more.

### Functions

- **`add_breakpoint(address, condition=None, ignore_count=0, enable=True, one_shot=False, location=None)`**
  Adds a breakpoint at the specified address.

- **`add_watchpoint(address, size, condition=None, ignore_count=0, enable=True, read_write='rw')`**
  Adds a watchpoint to monitor memory access.

- **`allocate_memory(size)`**
  Allocates memory in the inferior process.

- **`allocated_memory_gen_id()`**
  Generates a unique ID for allocated memory.

- **`attach(pid)`**
  Attaches to an existing process by its PID.

- **`call_function_from_inferior(func_name, args, stack_frame_index=0)`**
  Calls a function within the inferior process.

- **`can_attach(pid)`**
  Checks if the current process can attach to the target PID.

- **`cancel_dissect_code()`**
  Cancels an ongoing code dissection operation.

- **`cancel_ongoing_command()`**
  Cancels any currently executing command in the inferior process.

- **`complete_command(command)`**
  Completes a given command string.

- **`continue_inferior()`**
  Resumes execution of the inferior process.

- **`convert_to_hex(value)`**
  Converts a value to its hexadecimal string representation.

- **`create_process(program, args=[])`**
  Creates and starts a new process.

- **`delete_breakpoint(address)`**
  Deletes a breakpoint at the specified address.

- **`detach()`**
  Detaches from the currently attached process.

- **`disassemble(address, count=10)`**
  Disassembles code starting from the given address.

- **`dissect_code(address, size)`**
  Dissects code at the specified address and size.

- **`examine_expression(expression)`**
  Examines the value of an expression in the inferior process.

- **`examine_expressions(expressions)`**
  Examines the values of multiple expressions.

- **`execute_func_temporary_interruption(func_name, args, interrupt_after_call=True)`**
  Executes a function and interrupts temporarily after its execution.

- **`execute_till_return(func_name, args)`**
  Executes a function until it returns.

- **`execute_with_temporary_interruption(command, interrupt_after_command=True)`**
  Executes a command and interrupts temporarily after its execution.

- **`find_closest_instruction_address(address)`**
  Finds the closest instruction address to the given address.

- **`find_entry_point()`**
  Finds the entry point of the executable.

- **`free_memory(address)`**
  Frees previously allocated memory in the inferior process.

- **`get_address_info(address)`**
  Retrieves information about a memory address.

- **`get_breakpoint_info(address)`**
  Retrieves information about a breakpoint.

- **`get_breakpoints_in_range(start_address, end_address)`**
  Retrieves all breakpoints within a specified address range.

- **`get_dissect_code_data()`**
  Retrieves the data from a code dissection operation.

- **`get_dissect_code_status()`**
  Retrieves the status of a code dissection operation.

- **`get_inferior_arch()`**
  Gets the architecture of the inferior process.

- **`get_inferior_pid()`**
  Gets the PID of the inferior process.

- **`get_modified_instructions()`**
  Retrieves information about modified instructions.

- **`get_stack_frame_info(level=0)`**
  Retrieves information about a specific stack frame.

- **`get_stack_frame_return_addresses()`**
  Retrieves the return addresses for all stack frames.

- **`get_stack_info()`**
  Retrieves information about the call stack.

- **`get_stacktrace_info()`**
  Retrieves a trace of the call stack.

- **`get_symbol_info(symbol_name)`**
  Retrieves information about a symbol.

- **`get_thread_info()`**
  Retrieves information about the current threads.

- **`get_track_breakpoint_info()`**
  Retrieves information about tracked breakpoints.

- **`get_track_watchpoint_info()`**
  Retrieves information about tracked watchpoints.

- **`handle_signal(signal_num, action)`**
  Handles a specific signal.

- **`handle_signals(signals, action)`**
  Handles multiple signals.

- **`hardware_breakpoint_available()`**
  Checks if hardware breakpoints are available.

- **`hex_dump(address, size)`**
  Performs a hexadecimal dump of memory.

- **`init_gdb()`**
  Initializes the GDB connection.

- **`init_referenced_dicts()`**
  Initializes referenced dictionaries.

- **`inject_with_advanced_injection(code, args, address, stack_frame_index=0)`**
  Injects code into the inferior process using advanced injection techniques.

- **`inject_with_dlopen_call(library_path, function_name, args, address, stack_frame_index=0)`**
  Injects code by calling a function in a dynamically loaded library.

- **`interrupt_inferior()`**
  Interrupts the execution of the inferior process.

- **`is_address_static(address)`**
  Checks if the given address is static.

- **`is_attached()`**
  Checks if the debugger is currently attached to a process.

- **`memory_handle(address, size, read_write)`**
  Handles memory read/write operations.

- **`modify_breakpoint(address, new_address=None, condition=None, ignore_count=None, enable=None, one_shot=None, location=None)`**
  Modifies an existing breakpoint.

### Tracer Class

- **`Tracer.cancel_trace()`**
  Cancels an ongoing trace operation.

- **`Tracer.set_breakpoint(address, condition=None, ignore_count=0, enable=True, one_shot=False, location=None)`**
  Sets a breakpoint within the tracer.

- **`Tracer.tracer_loop()`**
  Starts the main tracing loop.
```

--------------------------------

### Conditional Breakpoints Using GDB Expressions in PINCE

Source: https://github.com/korcankaraokcu/pince/wiki/GDB-Expressions

GDB expressions can be used to define conditions for setting breakpoints in PINCE. Examples include checking register values, logical combinations, and function call return values.

```text
$eax==0x523
$rax>0 && ($rbp<0 || $rsp==0)
printf($r10)==3
```

--------------------------------

### Get Stack Frame Information (Python)

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Retrieves detailed information about a specific stack frame in the current process. The function `get_stack_frame_info` takes a frame index as input, where 0 typically represents the current frame. The output is then printed to the console.

```python
frame_info = debugcore.get_stack_frame_info(0)  # Frame 0 is current
print(frame_info)
```

--------------------------------

### Read Pointer Chain Memory Address

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Reads a final memory address by following a chain of pointers starting from a base address. Supports symbolic names or hex strings for the base address and a list of integer offsets. Returns the chain of pointers and the final address.

```python
from libpince import debugcore, typedefs

request = typedefs.PointerChainRequest(
    base_address="game.exe+0x12345",  # Can be symbol or hex string
    offsets_list=[0x10, 0x20, 0x8]    # Offsets to follow
)

result = debugcore.read_pointer_chain(request)

if result:
    # Get each pointer in the chain
    for i, ptr in enumerate(result.pointer_chain):
        print(f"Level {i}: {hex(ptr)}")

    # Get final address
    final_addr = result.get_final_address()
    print(f"Final address: {hex(final_addr)}")

    # Read the value at final address
    health = debugcore.read_memory(final_addr, typedefs.VALUE_INDEX.INT32)
    print(f"Health: {health}")
else:
    print("Failed to read pointer chain - invalid address in chain")
```

--------------------------------

### Compile GDB Locally with compile_gdb.sh

Source: https://github.com/korcankaraokcu/pince/blob/master/README.md

This describes the usage of the `compile_gdb.sh` script, which allows users to compile a custom version of GDB locally. This is useful if the default GDB version causes issues.

```bash
# Usage instructions for compile_gdb.sh would go here, but are not provided in the source text.
# Refer to the script's comments for details.
```

--------------------------------

### Pince Typedefs - User Paths

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Defines user-specific configuration paths for Pince.

```APIDOC
## Pince Typedefs - User Paths

### USER_PATHS

Constants for user configuration file locations.

- **CONFIG** ('.config/')
- **GDBINIT** ('.config/PINCE/gdbinit')
- **GDBINIT_AA** ('.config/PINCE/gdbinit_after_attach')
- **PINCEINIT** ('.config/PINCE/pinceinit.py')
- **PINCEINIT_AA** ('.config/PINCE/pinceinit_after_attach.py')
```

--------------------------------

### libpince.debugcore.get_stack_info

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Fetches information about the current stack, with an option to view it from the base pointer (EBP/RBP).

```APIDOC
## GET /debugcore/stack_info

### Description
Returns information about the current stack. Optionally, can view the stack starting from the base pointer (EBP/RBP).

### Method
GET

### Endpoint
/debugcore/stack_info

### Parameters
#### Query Parameters
- **from_base_pointer** (bool) - Optional - If true, view the stack starting from the base pointer (EBP/RBP). Defaults to false.

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **list** - A list of lists, where each inner list contains stack pointer information, its hexadecimal value, and a pointer interpretation. The format is [[stack_pointer_info1, hex_value1, pointer_info1], ...].
  - `stack_pointer_info`: Hex address and distance from stack pointer (e.g., '0x7ffd0d232f88(rsp+0xff8)').
  - `hex_value`: The value held by the corresponding address (e.g., '0x1bfda20').
  - `pointer_info`: Interpretation of the value at `hex_value`, indicating if it points to a string, a symbol, or is null.

#### Response Example
```json
{
  "example": [
    ["0x7ffd0d232f88(rsp+0xff8)", "0x1bfda20", "(str)Some String"],
    ["0x7ffd0d232f90(rsp+0xff0)", "0x401000", "(ptr)<main>"]
  ]
}
```
```

--------------------------------

### Analyze Call Stack and Stack Frames

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Provides functions for analyzing the call stack and stack frames during debugging sessions. It includes capabilities to pause the process, retrieve stack trace information (return addresses and frame addresses), and specifically get a list of return addresses from stack frames. Uses the `debugcore` module.

```python
from libpince import debugcore

# Pause the process
debugcore.interrupt_inferior()

# Get stack trace information
stack_trace = debugcore.get_stacktrace_info()
for return_addr, frame_addr in stack_trace:
    print(f"Return: {return_addr}")
    print(f"Frame:  {frame_addr}")
    print()

# Get stack frame return addresses
return_addrs = debugcore.get_stack_frame_return_addresses()
for addr in return_addrs:
    print(f"Return address: {addr}")
```

--------------------------------

### GDB Path and File Management

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Functions related to retrieving paths and files associated with GDB and PINCE.

```APIDOC
## GET /utils/gdb/default_path

### Description
Retrieves the default GDB path.

### Method
GET

### Endpoint
/utils/gdb/default_path

### Response
#### Success Response (200)
- **path** (str) - The default GDB path.

#### Response Example
```json
{
  "path": "/usr/bin/gdb"
}
```

## GET /utils/gdb/dissect_code_status_file

### Description
Gets the path of the dissect code status file for a given process ID.

### Method
GET

### Endpoint
/utils/gdb/dissect_code_status_file

### Parameters
#### Query Parameters
- **pid** (int | str) - Required - PID of the process.

### Request Example
```json
{
  "pid": 12345
}
```

### Response
#### Success Response (200)
- **path** (str) - The path to the dissect code status file.

#### Response Example
```json
{
  "path": "/tmp/pince/12345/dissect_code.status"
}
```

## GET /utils/pince/file

### Description
Gets the path of the IPC file sent to custom GDB commands from PINCE for a given process ID.

### Method
GET

### Endpoint
/utils/pince/file

### Parameters
#### Query Parameters
- **pid** (int | str) - Required - PID of the process.

### Request Example
```json
{
  "pid": 12345
}
```

### Response
#### Success Response (200)
- **path** (str) - The path to the IPC file.

#### Response Example
```json
{
  "path": "/tmp/pince/12345/pince.ipc"
}
```

## GET /utils/gdb/command_file

### Description
Gets the path of the GDB command file for a given process ID.

### Method
GET

### Endpoint
/utils/gdb/command_file

### Parameters
#### Query Parameters
- **pid** (int | str) - Required - PID of the process.

### Request Example
```json
{
  "pid": 12345
}
```

### Response
#### Success Response (200)
- **path** (str) - The path to the GDB command file.

#### Response Example
```json
{
  "path": "/tmp/pince/12345/gdb.cmd"
}
```

## GET /utils/logging_file

### Description
Gets the path of the GDB logfile for a given process ID.

### Method
GET

### Endpoint
/utils/logging_file

### Parameters
#### Query Parameters
- **pid** (int | str) - Required - PID of the process.

### Request Example
```json
{
  "pid": 12345
}
```

### Response
#### Success Response (200)
- **path** (str) - The path to the GDB logfile.

#### Response Example
```json
{
  "path": "/tmp/pince/12345/gdb.log"
}
```
```

--------------------------------

### Replace Instruction with NOPs in x86 Assembly

Source: https://github.com/korcankaraokcu/pince/wiki/Modifying-Game-Code

The NOP (No Operation) instruction, represented by the machine code byte `0x90` in x86 assembly, does nothing. It can be used to nullify existing instructions in game code, effectively disabling their functionality. This example demonstrates replacing an `add DWORD PTR [rax], 0xffffffff` instruction with three `0x90` bytes.

```x86asm
add DWORD PTR [rax], 0xffffffff
; Replaced with 3 NOPs (0x90)
```

```hex
0x90 0x90 0x90
```

--------------------------------

### libpince.debugcore.get_breakpoint_info()

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Retrieves a list of all current breakpoints and watchpoints. Returns detailed information for each breakpoint.

```APIDOC
## GET libpince.debugcore.get_breakpoint_info()

### Description
Returns current breakpoint/watchpoint list. GDB’s python API can’t detect hardware breakpoints, that’s why we are using parser for this job.

### Method
GET

### Endpoint
/libpince.debugcore/get_breakpoint_info

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **breakpoints** (list) - A list of breakpoint information. Each item is a tuple with the following fields:
  - **number** (str) - GDB breakpoint number.
  - **breakpoint_type** (str) - Type of breakpoint (e.g., 'breakpoint', 'watchpoint').
  - **disp** (str) - Disposition of the breakpoint (e.g., 'keep', 'delete').
  - **enabled** (str) - Whether the breakpoint is enabled ('y' or 'n').
  - **address** (str) - The memory address of the breakpoint.
  - **size** (int) - The size of the breakpoint (if applicable).
  - **on_hit** (str) - Action to perform when the breakpoint is hit.
  - **hit_count** (str) - Number of times the breakpoint has been hit.
  - **enable_count** (str) - Number of times the breakpoint will be hit before disabling.
  - **condition** (str) - The condition for the breakpoint to trigger.

#### Response Example
```json
{
  "breakpoints": [
    {
      "number": "1",
      "breakpoint_type": "breakpoint",
      "disp": "keep",
      "enabled": "y",
      "address": "0x12345678",
      "size": 1,
      "on_hit": "",
      "hit_count": "0",
      "enable_count": "0",
      "condition": ""
    }
  ]
}
```
```

--------------------------------

### File Loading Utility

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Loads data from a specified file path. Supports JSON and Pickle formats.

```APIDOC
## libpince.utils.load_file(file_path, load_method='json')

### Description
Loads data from the given path. Supports 'json' or 'pickle' load methods.

### Method
GET

### Endpoint
/utils/load_file

### Parameters
#### Query Parameters
- **file_path** (str) - Required - Path of the saved file
- **load_method** (str) - Optional - Can be "json" or "pickle". Defaults to "json".

### Response
#### Success Response (200)
- **data** (any) - The loaded data from the file. The type depends on the file content.
- **error** (str | None) - An error message if loading fails, otherwise None.

#### Response Example
```json
{
  "data": {"key": "value"},
  "error": null
}
```
```

--------------------------------

### Directory and Module Information

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Functions for retrieving directory paths and module names.

```APIDOC
## GET /utils/libpince_directory

### Description
Gets the directory path where the libpince library resides.

### Method
GET

### Endpoint
/utils/libpince_directory

### Response
#### Success Response (200)
- **path** (str) - A string pointing to the libpince directory.

#### Response Example
```json
{
  "path": "/path/to/libpince"
}
```

## GET /utils/logo_directory

### Description
Gets the directory path for logos.

### Method
GET

### Endpoint
/utils/logo_directory

### Response
#### Success Response (200)
- **path** (str) - A string pointing to the logo directory.

#### Response Example
```json
{
  "path": "/path/to/logos"
}
```

## GET /utils/media_directory

### Description
Gets the directory path for media files.

### Method
GET

### Endpoint
/utils/media_directory

### Response
#### Success Response (200)
- **path** (str) - A string pointing to the media directory.

#### Response Example
```json
{
  "path": "/path/to/media"
}
```

## POST /utils/module_name

### Description
Gets the name of a given module without its package name.

### Method
POST

### Endpoint
/utils/module_name

### Parameters
#### Request Body
- **module** (object) - Required - A module object.

### Request Example
```json
{
  "module": "<module 'os' from '/usr/lib/python3.8/os.py'>"
}
```

### Response
#### Success Response (200)
- **name** (str) - The name of the module.

#### Response Example
```json
{
  "name": "os"
}
```
```

--------------------------------

### Execute Till Return

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Continues the execution of the inferior process until the current stack frame returns.

```APIDOC
## POST /debugcore/execute_till_return

### Description
Continues the execution of the inferior process until the current stack frame returns.

### Method
POST

### Endpoint
/debugcore/execute_till_return

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **status** (str) - Indicates the execution status.

#### Response Example
```json
{
  "status": "Execution continued until return."
}
```
```

--------------------------------

### Create Process

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Creates a new process for debugging. The current process will be detached even if this call fails. Use with caution and ensure data is saved beforehand.

```APIDOC
## POST /debugcore/create_process

### Description
Creates a new process for debugging and initializes some of the global variables. The current process will be detached even if the create_process call fails. Ensure your data is saved before calling this function.

### Method
POST

### Endpoint
/debugcore/create_process

### Parameters
#### Query Parameters
- **process_path** (str) - Required - Absolute path of the target binary
- **args** (str) - Optional - Arguments for the inferior process
- **ld_preload_path** (str) - Optional - Path of the preloaded .so file
- **gdb_path** (str) - Optional - Path of the gdb binary (defaults to /bin/gdb). Ignored if GDB is already initialized.

### Request Example
```json
{
  "process_path": "/path/to/your/binary",
  "args": "--some-arg value",
  "ld_preload_path": "/path/to/preload.so",
  "gdb_path": "/usr/bin/gdb"
}
```

### Response
#### Success Response (200)
- **success** (bool) - True if the process has been created successfully, False otherwise.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Regexes Module

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/modules.md

Documentation for the regexes module within Pince, primarily for GDB command parsing.

```APIDOC
## Regexes Module

### Description
This module provides regular expressions and utilities for parsing GDB output and commands.

### Endpoints

#### Function
- `gdb_command_source()`: Generates a source command for GDB based on provided arguments.

### Request Body
Not applicable.

### Response
Returns a string representing a GDB command.
```

--------------------------------

### Attach to Process using libpince

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Connects GDB to a target process using its Process ID (PID). It initializes the debugging session and handles potential connection issues like permissions or existing debuggers. The function returns an enum indicating the success or failure reason.

```python
from libpince import debugcore, typedefs

# Initialize GDB (optional, attach() does this automatically)
debugcore.init_gdb()

# Attach to a process by PID
pid = 12345
result = debugcore.attach(pid)

if result == typedefs.ATTACH_RESULT.SUCCESSFUL:
    print(f"Successfully attached to process {pid}")
elif result == typedefs.ATTACH_RESULT.PROCESS_NOT_VALID:
    print("Process does not exist")
elif result == typedefs.ATTACH_RESULT.PERM_DENIED:
    print("Permission denied - try running as root")
elif result == typedefs.ATTACH_RESULT.ALREADY_TRACED:
    print("Process is already being traced by another debugger")

# Detach when done
debugcore.detach()
```

--------------------------------

### libpince.debugcore.get_address_info(expression)

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Retrieves information about a given expression by running the 'info symbol' GDB command. Returns the command's output.

```APIDOC
## GET libpince.debugcore.get_address_info(expression)

### Description
Runs the gdb command “info symbol” for given expression and returns the result of it.

### Method
GET

### Endpoint
/libpince.debugcore/get_address_info

### Parameters
#### Query Parameters
- **expression** (str) - Required - Any gdb expression to get information about.

### Request Example
None (parameters are in query string)

### Response
#### Success Response (200)
- **symbol_info** (str) - The result of the “info symbol” command for the given expression.

#### Response Example
```json
{
  "symbol_info": "Symbol \"my_variable\" is a variable at address 0x12345678."
}
```
```

--------------------------------

### Process and Memory Management

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Functions for attaching to processes, managing memory allocation, and checking attachability.

```APIDOC
## Process and Memory Management

### Description
Provides functionalities for attaching to a process, managing allocated memory, and checking if a process can be attached to.

### `attach(pid, gdb_path='/bin/gdb')`

Attaches gdb to the target process and initializes global variables.

#### Parameters
* **pid** (int | str) – PID of the process to attach to.
* **gdb_path** (str) – Path to the gdb binary. Defaults to '/bin/gdb'.

#### Returns
A member of typedefs.ATTACH_RESULT.

#### Return type
int

#### NOTE
If gdb is already initialized, `gdb_path` will be ignored.

### `allocated_memory_gen_id`

A global variable used for generating IDs for allocated memory. Historically, PINCE's support for GDB/MI commands was limited due to older GDB versions, leading to parsing console output. Newer versions of GDB improve this significantly.

### `allocate_memory(*args, **kwargs)`
Allocates memory with specified arguments.

### `can_attach(pid)`

Checks if the target process can be attached to.

#### Parameters
* **pid** (int | str) – PID of the process to check.

#### Returns
True if attaching is successful, False otherwise.

#### Return type
bool
```

--------------------------------

### DebugCore Functions

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/modules.md

This section details the functions available in the Pince debugcore module for interacting with and controlling debugged processes.

```APIDOC
## DebugCore Functions

### Description
Provides a comprehensive set of functions for debugging, including instruction manipulation, memory and register access, search capabilities, and process control.

### Endpoints
This section lists individual functions rather than HTTP endpoints.

#### Functions
- `modify_instruction()`: Modifies a specific instruction in the debugged process.
- `nop_instruction()`: Replaces an instruction with a NOP (No Operation) instruction.
- `parse_and_eval()`: Parses and evaluates a given expression within the debugged process context.
- `read_float_registers()`: Reads the values of floating-point registers.
- `read_memory()`: Reads a specified range of memory from the debugged process.
- `read_pointer_chain()`: Reads a chain of pointers starting from a given address.
- `read_registers()`: Reads the values of general-purpose registers.
- `restore_instruction()`: Restores a previously modified instruction.
- `search_functions()`: Searches for functions within the debugged process's memory.
- `search_opcode()`: Searches for a specific opcode sequence in memory.
- `search_referenced_calls()`: Finds calls that reference a specific address.
- `search_referenced_strings()`: Finds strings referenced by code.
- `send_command()`: Sends a raw GDB command to the debugger.
- `set_convenience_variable()`: Sets a GDB convenience variable.
- `set_gdb_output_mode()`: Configures the output mode for GDB.
- `set_interrupt_signal()`: Sets the signal used for interrupting the process.
- `set_logging()`: Enables or disables logging for debugging information.
- `set_pince_paths()`: Sets the paths for Pince to use.
- `set_register_flag()`: Sets or clears a flag in a register.
- `state_observe_thread()`: Observes the state of a specific thread.
- `step_instruction()`: Executes a single instruction.
- `step_over_instruction()`: Executes a single instruction, stepping over function calls.
- `toggle_attach()`: Attaches to or detaches from a process.
- `track_breakpoint()`: Sets a breakpoint that tracks its hit count.
- `track_watchpoint()`: Sets a watchpoint that tracks its hit count.
- `wait_for_stop()`: Waits for the debugged process to stop execution.
- `write_memory()`: Writes data to a specified memory address.

### Request Body
Not applicable for individual function calls in this context; refer to specific function documentation if available.

### Response
Responses vary depending on the function called. Refer to specific function documentation for details.
```

--------------------------------

### libpince.debugcore.get_inferior_arch()

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Retrieves the architecture of the current inferior process. Returns an integer representing the architecture.

```APIDOC
## GET libpince.debugcore.get_inferior_arch()

### Description
Returns the architecture of the current inferior.

### Method
GET

### Endpoint
/libpince.debugcore/get_inferior_arch

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **architecture** (int) - An integer representing the inferior's architecture (member of typedefs.INFERIOR_ARCH).

#### Response Example
```json
{
  "architecture": 1
}
```
```

--------------------------------

### Command Execution and Utility Functions

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Functions for executing commands in the inferior, converting values, and completing GDB commands.

```APIDOC
## Command Execution and Utility Functions

### Description
Utility functions for interacting with the debugged process, including calling functions, canceling commands, and converting data formats.

### `call_function_from_inferior(expression)`

Calls the given function expression from the inferior process.

#### Parameters
* **expression** (str) – Any gdb expression representing a function call.

#### Returns
A tuple containing the assigned value and the result, both as strings. Returns a tuple of (False, False) if the call fails.

#### Return type
tuple

#### Examples
```python
call_function_from_inferior("printf('123')")
# Returns: ('$26', '3')
```

### `cancel_dissect_code()`
Finishes the current dissect code process early.

### `cancel_ongoing_command()`

Cancels the last GDB command sent if it is still pending.

#### Returns
True if the cancellation was successful, False if there was nothing to cancel.

#### Return type
bool

### `complete_command(gdb_command)`

Tries to complete the given GDB command and returns possible completion suggestions.

#### Parameters
* **gdb_command** (str) – The GDB command to complete.

#### Returns
Possible completions as a list of strings.

#### Return type
list

### `continue_inferior()`
Resumes the execution of the inferior process.

### `convert_to_hex(expression)`

Converts numeric values within a GDB expression to their hexadecimal equivalents. This function respects edge cases such as indexed maps and keeps indices in decimal format.

#### Parameters
* **expression** (str) – Any GDB expression containing numeric values.

#### Returns
The converted string with numeric values in hexadecimal format.

#### Return type
str
```

--------------------------------

### Add and Manage Breakpoints

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Sets hardware or software breakpoints at specified addresses or symbols. Breakpoints can be configured with hit actions, conditions, and can be enabled, disabled, or deleted. Hardware breakpoints are preferred for efficiency.

```python
from libpince import debugcore, typedefs

# Add a hardware breakpoint (preferred, uses CPU debug registers)
bp_num = debugcore.add_breakpoint(
    "main",  # Can be function name, symbol, or hex address
    breakpoint_type=typedefs.BREAKPOINT_TYPE.HARDWARE,
    on_hit=typedefs.BREAKPOINT_ON_HIT.BREAK
)

if bp_num:
    print(f"Breakpoint {bp_num} set successfully")

# Add a software breakpoint at specific address
bp_num2 = debugcore.add_breakpoint(
    "0x401000",
    breakpoint_type=typedefs.BREAKPOINT_TYPE.SOFTWARE,
    on_hit=typedefs.BREAKPOINT_ON_HIT.BREAK
)

# Modify breakpoint condition
debugcore.modify_breakpoint(
    bp_num,
    typedefs.BREAKPOINT_MODIFY.CONDITION,
    condition="$rax > 100"
)

# Enable/disable breakpoint
debugcore.modify_breakpoint(bp_num, typedefs.BREAKPOINT_MODIFY.DISABLE)
debugcore.modify_breakpoint(bp_num, typedefs.BREAKPOINT_MODIFY.ENABLE)

# Delete breakpoint
debugcore.delete_breakpoint(bp_num)
```

--------------------------------

### libpince.debugcore.get_modified_instructions

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Retrieves a dictionary of currently modified instructions, mapping instruction addresses to their pre-modification state.

```APIDOC
## GET /debugcore/modified_instructions

### Description
Returns currently modified instructions.

### Method
GET

### Endpoint
/debugcore/modified_instructions

### Parameters
#### Query Parameters
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **dict** (dict) - A dictionary where the key is the start address of the instruction and the value is the state of the instruction before modification.

#### Response Example
```json
{
  "example": {
    "0x12345678": "original_instruction_bytes"
  }
}
```
```

--------------------------------

### Trace Execution Flow with Python

Source: https://context7.com/korcankaraokcu/pince/llms.txt

Utilizes the Tracer class to record instruction execution flow, similar to Cheat Engine's trace feature. It allows setting breakpoints with conditions, collecting register data, and analyzing the trace output. Requires the 'libpince' library.

```python
from libpince import debugcore, typedefs
from threading import Thread

# Create a tracer instance
tracer = debugcore.Tracer()

# Set up the trace breakpoint
bp_num = tracer.set_breakpoint(
    expression="0x401000",          # Start tracing when this address is hit
    max_trace_count=1000,           # Maximum instructions to trace
    trigger_condition="$rax > 0",   # Optional: only start when condition is met
    stop_condition="$rip == 0x401500",  # Optional: stop when this is true
    step_mode=typedefs.STEP_MODE.SINGLE_STEP,  # or STEP_OVER
    stop_after_trace=False,         # Continue process after tracing
    collect_registers=True          # Collect register values at each step
)

if bp_num:
    # Start the tracer in a background thread
    tracer_thread = Thread(target=tracer.tracer_loop)
    tracer_thread.start()

    # Continue process to trigger the trace
    debugcore.continue_inferior()

    # Wait for trace to complete
    tracer_thread.join()

    # Get trace data (tree structure)
    tree, root_index = tracer.trace_data

    for node in tree:
        line_info, parent, children = node
        if line_info[0]:  # Not empty root node
            instruction, registers = line_info
            print(f"Instruction: {instruction}")
            if registers:
                print(f"  RAX: {registers.get('rax', 'N/A')}")

# Cancel trace early if needed
# tracer.cancel_trace()
```

--------------------------------

### libpince.debugcore.get_thread_info

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Invokes the GDB 'info threads' command and returns information about the current thread.

```APIDOC
## GET /debugcore/thread_info

### Description
Invokes the “info threads” command in GDB and returns the line corresponding to the current thread.

### Method
GET

### Endpoint
/debugcore/thread_info

### Parameters
#### Query Parameters
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **str** - A string containing the current thread's information as output by GDB. Returns `None` if the output does not match the expected format.

#### Response Example
```json
{
  "example": "* 1 Thread 0x7ffc5f87f6a0 (LWP 1234) \"main\" 0x00007fd1d639412d in poll ()"
}
```
```

--------------------------------

### libpince.debugcore.handle_signal

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Configures GDB's behavior when the process receives a specific signal.

```APIDOC
## POST /debugcore/handle_signal

### Description
Decides on what GDB will do when the process receives a signal.

### Method
POST

### Endpoint
/debugcore/handle_signal

### Parameters
#### Request Body
- **signal_name** (str) - Required - The name of the signal (e.g., 'SIGINT', 'SIGSEGV').
- **stop** (bool) - Required - If true, GDB will stop the program and print to the console when the signal is received.
- **pass_to_program** (bool) - Required - If true, the signal will be passed to the program being debugged.

### Request Example
```json
{
  "signal_name": "SIGSEGV",
  "stop": true,
  "pass_to_program": false
}
```

### Response
#### Success Response (200)
- **None** - This endpoint does not return a value upon successful execution.

#### Response Example
```json
{
  "example": "null"
}
```
```

--------------------------------

### libpince.debugcore.get_stack_frame_return_addresses

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Retrieves a list of return addresses for all stack frames.

```APIDOC
## GET /debugcore/stack_frame_return_addresses

### Description
Returns the return addresses of all stack frames.

### Method
GET

### Endpoint
/debugcore/stack_frame_return_addresses

### Parameters
#### Query Parameters
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **list** - A list of strings, where each string represents the return address information for a stack frame in the format 'Return address of frame+symbol'.

#### Response Example
```json
{
  "example": [
    "0x40c431 <_start>",
    "0x40c500 <main>"
  ]
}
```
```

--------------------------------

### libpince.debugcore.get_symbol_info

Source: https://github.com/korcankaraokcu/pince/blob/master/docs/source/libpince.md

Executes the GDB 'info address' command for a given expression and returns the result.

```APIDOC
## GET /debugcore/symbol_info

### Description
Runs the gdb command “info address” for the given expression and returns its result.

### Method
GET

### Endpoint
/debugcore/symbol_info

### Parameters
#### Query Parameters
- **expression** (str) - Required - Any valid GDB expression for which to get address information.

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **str** - The output of the GDB 'info address' command for the specified expression.

#### Response Example
```json
{
  "example": "Symbol \"my_variable\" is a variable at address 0x12345678."
}
```
```