PINCE

https://korcankaraokcu.github.io/PINCE/
Admin
PINCE is a GDB front-end and reverse engineering tool designed for memory searching, debugging, and...
Tokens:27,994
Snippets:235
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### get_script_directory()

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get main script directory.

```APIDOC
## get_script_directory()

### Description
Get main script directory.

### Returns
- **directory** (`str`) - A string pointing to the main script directory
```

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

### get_process_start_time(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the process start time (field 22 of /proc/<pid>/stat, clock ticks since boot). Combined with pid this uniquely identifies a process instance, guarding against PID reuse.

```APIDOC
## get_process_start_time(pid)

### Description
Returns the process start time (field 22 of /proc/<pid>/stat, clock ticks since boot). Combined with pid this uniquely identifies a process instance, guarding against PID reuse.

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

### Returns
- **starttime** (`int` | `None`) - starttime field, or None on error
```

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

### get_region_dict(pid_or_memory_regions)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns memory regions of a process as a dictionary where key is the path tail and value is the list of the corresponding start addresses of the tail, empty paths will be ignored. Also adds shortcuts for file extensions. Returned dict will include both sonames, with and without version information.

```APIDOC
## get_region_dict(pid_or_memory_regions)

### Description
Returns memory regions of a process as a dictionary where key is the path tail and value is the list of the corresponding start addresses of the tail, empty paths will be ignored. Also adds shortcuts for file extensions. Returned dict will include both sonames, with and without version information.

### Parameters
- **pid_or_memory_regions** (`int` | `list`[`tuple`[`str`, `...`]]) - Required - PID of the process or output from get_regions

### Returns
- **dict** (`dict`[`str`, `list`[`str`]]) - {file_name:start_address_list}
```

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

### get_user_ids()

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Gets uid and gid of the user who invoked PINCE/libpince. Resolves real user if invoked through sudo/pkexec.

```APIDOC
## get_user_ids()

### Description
Gets uid and gid of the user who invoked PINCE/libpince. Resolves real user if invoked through sudo/pkexec.

### Returns
- **tuple** (`tuple`[`str`, `str`]) - uid and gid of the real invoking user.
```

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

### get_track_watchpoint_file(pid, watchpoint_list)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of track watchpoint file for given pid and watchpoint.

```APIDOC
## get_track_watchpoint_file(pid, watchpoint_list)

### Description
Get the path of track watchpoint file for given pid and watchpoint.

### Parameters
- **pid** (`int` | `str`) - Required - PID of the process
- **watchpoint_list** (`list` | `str`) - Required - Numbers of the watchpoints

### Returns
- **path** (`str`) - Path of track watchpoint file
```

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

### get_to_pince_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of IPC file sent to PINCE from custom gdb commands for given pid.

```APIDOC
## get_to_pince_file(pid)

### Description
Get the path of IPC file sent to PINCE from custom gdb commands for given pid.

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

### Returns
- **path** (`str`) - Path of IPC file
```

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

### PointerChainRequest

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/typedefs.html

Represents a pointer chain request with a base address and a list of offsets. Provides methods to serialize the request and get the base address as a string.

```APIDOC
## PointerChainRequest

### Description
Represents a pointer chain request with a base address and a list of offsets. Provides methods to serialize the request and get the base address as a string.

### Constructor
`PointerChainRequest(base_address: str | int, offsets_list: list[int] | None = None)`

#### Parameters
- **base_address** (str | int) - Required - The base address of where this pointer chain starts from. Can be str expression or int.
- **offsets_list** (list[int] | None) - Optional - List of offsets to reach the final pointed data. Can be None for no offsets. Last offset in list won't be dereferenced to emulate CE behaviour.

### Methods

#### serialize()
Returns a tuple containing the base address and offsets list.

#### get_base_address_as_str()
Returns the text representation of this pointer's base address.
```

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

### init_user_files() -> None

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Initializes user files by creating the root user directory if it doesn't exist and touching all files returned by typedefs.USER_PATHS.get_init_files().

```APIDOC
## init_user_files() -> None

### Description
Initializes user files by creating the root user directory if it doesn't exist and touching all files returned by typedefs.USER_PATHS.get_init_files().

### Method
Function

### Signature
init_user_files() -> None

### Parameters
None

### Returns
- **None**

### Behavior
- Gets the root user path from typedefs.USER_PATHS.ROOT.
- Creates the directory if it does not exist.
- For each file in typedefs.USER_PATHS.get_init_files(), creates the file if it doesn't exist (using pathlib.Path.touch).

### Example
```python
init_user_files()
```
```

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

### get_tmp_path(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the tmp directory of given pid.

```APIDOC
## get_tmp_path(pid)

### Description
Get the tmp directory of given pid.

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

### Returns
- **path** (`str`) - Path of tmp directory
```

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

### libpince.utils.assemble

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Assembles the given instructions.

```APIDOC
## libpince.utils.assemble

### Description
Assembles the given instructions.

### Parameters
- **instructions** (`str`) - Required - A string of instructions, multiple entries separated by ;
- **address** (`int`) - Required - Starting address of the instructions
- **inferior_arch** (`int`) - Required - Can be a member of typedefs.INFERIOR_ARCH

### Returns
A tuple of (list, int) –> Assembled bytes (list of int) and instruction count (int) None: If there was an error

### Return Type
`tuple`[`list`[`int`], `int`] | `None`
```

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

### get_trace_status_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of trace status file for given pid.

```APIDOC
## get_trace_status_file(pid)

### Description
Get the path of trace status file for given pid.

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

### Returns
- **path** (`str`) - Path of trace status file
```

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

### libpince.utils.disassemble

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the instructions from the given array of bytes.

```APIDOC
## libpince.utils.disassemble

### Description
Returns the instructions from the given array of bytes.

### Parameters
- **aob** (`str`) - Required - Opcode bytes of the instruction as an array of bytes
- **address** (`int`) - Required - The address where the instruction starts from
- **inferior_arch** (`int`) - Required - Architecture type (x86, x64). Can be a member of typedefs.INFERIOR_ARCH

### Returns
Instructions, multiple entries are separated with ; None: If there was an error

### Return Type
`str` | `None`
```

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

### libpince.utils.execute_script

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Loads and executes the script in the given path.

```APIDOC
## libpince.utils.execute_script

### Description
Loads and executes the script in the given path.

### Parameters
- **file_path** (`str`) - Required - Self-explanatory

### Returns
(module, exception) module–> Loaded script as module exception–> traceback as str
Returns (None, exception) if fails to load the script Returns (module, None) if script gets loaded successfully

### Return Type
`tuple`[`ModuleType` | `None`, `str` | `None`]
```

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

### get_referenced_calls_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of referenced calls dict file for given pid.

```APIDOC
## get_referenced_calls_file(pid)

### Description
Get the path of referenced calls dict file for given pid.

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

### Returns
- **path** (`str`) - Path of referenced calls dict file
```

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

### get_referenced_strings_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of referenced strings dict file for given pid.

```APIDOC
## get_referenced_strings_file(pid)

### Description
Get the path of referenced strings dict file for given pid.

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

### Returns
- **path** (`str`) - Path of referenced strings dict file
```

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

### USER_PATHS

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Static method to retrieve initialization file paths.

```APIDOC
## USER_PATHS.get_init_files()

### Description
Returns a tuple of initialization file paths.

### Method
static

### Returns
- **tuple[str, str, str, str]** - The initialization file paths.
```

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

### get_referenced_jumps_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of referenced jumps dict file for given pid.

```APIDOC
## get_referenced_jumps_file(pid)

### Description
Get the path of referenced jumps dict file for given pid.

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

### Returns
- **path** (`str`) - Path of referenced jumps dict file
```

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

### execute_script(file_path: str) -> tuple[ModuleType | None, str | None]

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Loads and executes the script at the given file path. Returns a tuple containing the loaded module and an exception traceback string if an error occurs.

```APIDOC
## execute_script(file_path: str) -> tuple[ModuleType | None, str | None]

### Description
Loads and executes the script at the given file path. Returns a tuple containing the loaded module and an exception traceback string if an error occurs.

### Parameters
- **file_path** (str) - Required - Path to the script file.

### Returns
- **tuple**: (module, exception) where module is the loaded script as a module or None, and exception is a traceback string or None.

```

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

### libpince.utils.create_ipc_path

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Creates the IPC directory of given pid.

```APIDOC
## libpince.utils.create_ipc_path

### Description
Creates the IPC directory of given pid.

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

### Return Type
`None`
```

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

### get_track_breakpoint_file(pid, breakpoint_number)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Get the path of track breakpoint file for given pid and breakpoint.

```APIDOC
## get_track_breakpoint_file(pid, breakpoint_number)

### Description
Get the path of track breakpoint file for given pid and breakpoint.

### Parameters
- **pid** (`int` | `str`) - Required - PID of the process
- **breakpoint_number** (`int` | `str`) - Required - Breakpoint number

### Returns
- **path** (`str`) - Path of track breakpoint file
```

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

### libpince.utils.create_tmp_path

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Creates the tmp directory of given pid.

```APIDOC
## libpince.utils.create_tmp_path

### Description
Creates the tmp directory of given pid.

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

### Return Type
`None`
```

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

### PointerChainResult

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Represents the result of resolving a pointer chain. Provides methods to get the final address and individual pointers.

```APIDOC
## PointerChainResult class

### Description
Represents the result of a pointer chain resolution.

### Methods

#### get_final_address()
Returns the final address of the pointer chain.

- **Return type**: `int` | `None`

#### get_final_address_as_hex()
Returns the hex representation of the final address.

- **Return type**: `str` | `None`

#### get_pointer_by_index(index)
Returns the pointer at the given index.

- **Parameters**:
  - **index** (int) - The index of the pointer.
- **Return type**: `int` | `None`

### Attributes
- **pointer_chain**: `list[int]` - The list of pointers in the chain.

```

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

### load_file(file_path, load_method)

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Loads data from a file in JSON or pickle format. Returns the loaded data or None on failure.

```APIDOC
## load_file(file_path, load_method)

### Description
Loads data from a file using the specified method (json or pickle).

### Parameters
- **file_path** (str) - Required - Path of the file to load.
- **load_method** (str) - Required - Either "json" or "pickle".

### Returns
- **Any** - The loaded data (type depends on the file content).
- **None** - If loading fails or load_method is unsupported.

### Errors
- Logs an exception and returns None if an error occurs during loading.
- Logs an error and returns None if load_method is unsupported.
```

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

### get_libpince_directory()

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the directory path where the libpince module resides. This function takes no parameters.

```APIDOC
## get_libpince_directory()

### Description
Get libpince directory.

### Method
Function Call

### Signature
```python
libpince.utils.get_libpince_directory() -> str
```

### Parameters
None

### Returns
- **str** - A string pointing to the libpince directory.
```

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

### get_user_path(user_path: str) -> str

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Returns the specified user path for the current user by joining the user's home directory with the given path.

```APIDOC
## get_user_path(user_path: str) -> str

### Description
Returns the specified user path for the current user by joining the user's home directory with the given path.

### Parameters
- **user_path** (str) - Required - Can be a member of typedefs.USER_PATHS.

### Returns
- **str**: Specified user path of the current user.

```

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

### ScriptEntry

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

An entry that runs a Libpince Engine script when toggled. Only the script is serialized, and a namespace is maintained across enables/disables.

```APIDOC
## ScriptEntry class

### Description
An address table row that runs a Libpince Engine script when toggled instead of freezing a value. Only the script is serialized to the cheat table. Namespace is built on first enable and kept so variables set by the [ENABLE] section survive into a later [DISABLE] run within the same session.

### Attributes
- **namespace**: `dict[str, Any] | None` - Namespace for script variables.

```

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

### create_ipc_path(pid)

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Creates the IPC directory for the given process ID. If the directory already exists, it is removed and recreated. Also creates an empty command file for GDB.

```APIDOC
## create_ipc_path(pid)

### Description
Creates the IPC directory for the given process ID. If the directory already exists, it is removed and recreated. Also creates an empty command file for GDB.

### Method
Function

### Signature
```python
def create_ipc_path(pid: int | str) -> None
```

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

### Returns
- **None**

```

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

### assemble(instructions: str, address: int, inferior_arch: int) -> tuple[list[int], int] | None

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Assembles a string of instructions into machine code. Returns a tuple containing the assembled bytes as a list of integers and the instruction count, or None on error.

```APIDOC
## assemble

### Description
Assembles the given instructions.

### Method
Function

### Signature
```python
def assemble(instructions: str, address: int, inferior_arch: int) -> tuple[list[int], int] | None
```

### Parameters
- **instructions** (str) - Required - A string of instructions, multiple entries separated by ;.
- **address** (int) - Required - Starting address of the instructions.
- **inferior_arch** (int) - Required - Can be a member of typedefs.INFERIOR_ARCH.

### Returns
- **tuple** - A tuple of (list, int) --> Assembled bytes (list of int) and instruction count (int).
- **None** - If there was an error.

### Example
```python
result = assemble("nop; ret", 0x1000, typedefs.INFERIOR_ARCH.ARCH_64)
```
```

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

### get_user_home_dir()

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Returns the home directory of the current user. It uses the uid from get_user_ids() to look up the passwd entry, falling back to os.path.expanduser if not found.

```APIDOC
## get_user_home_dir()

### Description
Returns the home directory of the current user. It uses the uid from get_user_ids() to look up the passwd entry, falling back to os.path.expanduser if not found.

### Returns
- **str**: Home directory of the current user.

```

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

### get_user_ids()

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Returns the uid and gid of the real invoking user. It checks environment variables SUDO_UID, PKEXEC_UID, and SUDO_GID, falling back to the current process user if not set.

```APIDOC
## get_user_ids()

### Description
Returns the uid and gid of the real invoking user. It checks environment variables SUDO_UID, PKEXEC_UID, and SUDO_GID, falling back to the current process user if not set.

### Returns
- **tuple (str, str)**: A tuple containing the uid and gid as strings.

```

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

### get_gdb_command_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the path to the gdb command file for the given process ID.

```APIDOC
## get_gdb_command_file(pid)

### Description
Get the path of gdb command file of given pid.

### Method
Function Call

### Signature
```python
libpince.utils.get_gdb_command_file(pid: int | str) -> str
```

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

### Returns
- **str** - Path of gdb command file.
```

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

### libpince.utils.execute_command_as_user

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Executes given command as the original user who invoked PINCE.

```APIDOC
## libpince.utils.execute_command_as_user

### Description
Executes given command as the original user who invoked PINCE.

### Parameters
- **command** (`str`) - Required - Command that’ll be invoked from the shell

### Return Type
`None`
```

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

### get_process_list()

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns a list of processes with their PID, user, and process name.

```APIDOC
## get_process_list()

### Description
Returns a list of processes.

### Method
Function Call

### Signature
```python
libpince.utils.get_process_list() -> list[tuple[str, str, str]]
```

### Parameters
None

### Returns
- **list[tuple[str, str, str]]** - List of (pid, user, process_name) -> (str, str, str)
```

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

### create_tmp_path(pid)

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Creates the temporary directory for the given process ID. If the directory already exists, it is removed and recreated.

```APIDOC
## create_tmp_path(pid)

### Description
Creates the temporary directory for the given process ID. If the directory already exists, it is removed and recreated.

### Method
Function

### Signature
```python
def create_tmp_path(pid: int | str) -> None
```

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

### Returns
- **None**

```

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

### Constants and Enums

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Various constant classes used by libpince, including PATHS, REGISTERS, SCAN_INDEX, SCAN_MODE, SCAN_TYPE, STEP_MODE, and STOP_REASON.

```APIDOC
## Constants and Enums

### PATHS
Path constants used by libpince.

- **FROM_PINCE**: `/from_PINCE`
- **GDB**: `/bin/gdb`
- **IPC**: `/dev/shm/PINCE_IPC/`
- **TMP**: `/tmp/PINCE/`
- **TO_PINCE**: `/to_PINCE`

### REGISTERS
Register names.

- **FLAG**: `['cf', 'pf', 'af', 'zf', 'sf', 'tf', 'if', 'df', 'of']`
- **FLOAT**: ST registers: `['st0', 'st1', 'st2', 'st3', 'st4', 'st5', 'st6', 'st7']`
- **FLOAT.XMM_32**: `['xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7']`
- **FLOAT.XMM_64**: `['xmm0', ..., 'xmm15']`
- **GENERAL_32**: `['eax', 'ebx', 'ecx', 'edx', 'esi', 'edi', 'ebp', 'esp', 'eip']`
- **GENERAL_64**: `['rax', ..., 'r15']`
- **SEGMENT**: `['cs', 'ss', 'ds', 'es', 'fs', 'gs']`

### SCAN_INDEX
Scan value types.
- **ANY**: 8
- **AOB**: 10
- **FLOAT32**: 6
- **FLOAT64**: 7
- **FLOAT_ANY**: 5
- **INT16**: 2
- **INT32**: 3
- **INT64**: 4
- **INT8**: 1
- **INT_ANY**: 0
- **STRING**: 9

### SCAN_MODE
- **NEW**: 0
- **ONGOING**: 1

### SCAN_TYPE
- **BETWEEN**: 8
- **CHANGED**: 9
- **DECREASED**: 4
- **DECREASED_BY**: 5
- **EXACT**: 0
- **INCREASED**: 2
- **INCREASED_BY**: 3
- **LESS**: 6
- **MORE**: 7
- **NOT**: 1
- **UNCHANGED**: 10
- **UNKNOWN**: 11

### STEP_MODE
- **SINGLE_STEP**: 1
- **STEP_OVER**: 2

### STOP_REASON
- **DEBUG**: 2
- **PAUSE**: 1

```

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

### execute_command_as_user(command: str) -> None

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Executes a shell command as the original user who invoked PINCE, using sudo with the user's UID. Logs an error if the UID is invalid.

```APIDOC
## execute_command_as_user(command: str) -> None

### Description
Executes a shell command as the original user who invoked PINCE, using sudo with the user's UID. Logs an error if the UID is invalid.

### Method
Function

### Signature
execute_command_as_user(command: str) -> None

### Parameters
- **command** (str) - Required - Command that will be invoked from the shell.

### Returns
- **None**

### Behavior
- Retrieves the real user's UID via get_user_ids().
- If the UID is not a digit, logs an error and returns without executing.
- Otherwise, runs the command via subprocess.run with sudo -Eu #uid.

### Example
```python
execute_command_as_user("echo hello")
```
```

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

### get_module_dict(pid_or_memory_regions)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns a dictionary mapping module names or paths to their load bases, handling ambiguous basenames and versioned sonames.

```APIDOC
## get_module_dict(pid_or_memory_regions)

### Description
Returns logical module bases keyed by basename, or by full path when a basename is ambiguous. Unique shortcuts for versioned sonames are also included. Empty paths are ignored.

### Method
Function Call

### Signature
```python
libpince.utils.get_module_dict(pid_or_memory_regions: int | list[tuple[str, ...]]) -> dict[str, str]
```

### Parameters
- **pid_or_memory_regions** (int | list[tuple[str, ...]]) - Required - PID of the process or output from get_regions

### Returns
- **dict[str, str]** - {module_name_or_path: load_base}
```

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

### get_user_home_dir()

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the home directory of the current user.

```APIDOC
## get_user_home_dir()

### Description
Returns the home directory of the current user.

### Returns
- **home_dir** (`str`) - Home directory of the current user
```

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

### disassemble(aob: str, address: int, inferior_arch: int) -> str | None

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Disassembles an array of bytes (opcode) into human-readable instructions. Returns the instructions as a string with multiple entries separated by semicolons, or None on error.

```APIDOC
## disassemble

### Description
Returns the instructions from the given array of bytes.

### Method
Function

### Signature
```python
def disassemble(aob: str, address: int, inferior_arch: int) -> str | None
```

### Parameters
- **aob** (str) - Required - Opcode bytes of the instruction as an array of bytes (hex string).
- **address** (int) - Required - The address where the instruction starts from.
- **inferior_arch** (int) - Required - Architecture type (x86, x64). Can be a member of typedefs.INFERIOR_ARCH.

### Returns
- **str** - Instructions, multiple entries separated with ;.
- **None** - If there was an error.

### Example
```python
instructions = disassemble("90 90", 0x1000, typedefs.INFERIOR_ARCH.ARCH_64)
```
```

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

### get_default_gdb_path()

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the default path to the GDB executable. This function takes no parameters and returns a string.

```APIDOC
## get_default_gdb_path()

### Description
Returns the default path to the GDB executable.

### Method
Function Call

### Signature
```python
libpince.utils.get_default_gdb_path() -> str
```

### Parameters
None

### Returns
- **str** - The default GDB path.
```

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

### get_module_load_bias(pid, name_regex)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Finds the first mapped file whose basename matches the given regex and returns its load bias and absolute path.

```APIDOC
## get_module_load_bias(pid, name_regex)

### Description
Finds the first mapped file whose basename matches name_regex and returns its load bias and absolute path.

### Method
Function Call

### Signature
```python
libpince.utils.get_module_load_bias(pid: int, name_regex: str) -> tuple[int, str] | None
```

### Parameters
- **pid** (int) - Required - PID of the process
- **name_regex** (str) - Required - Regular expression to match against the basename of mapped files

### Returns
- **tuple[int, str] | None** - (load_bias, absolute_path) where load_bias is an int and absolute_path is a str. None if no matching module is found.
```

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

### search_processes

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Searches for processes by name or PID.

```APIDOC
## search_processes(name_or_pid)

### Description
Searches for processes by name or PID and returns a list of matching processes.

### Parameters
- **name_or_pid** (`str` | `int`) - Required - Process name or PID to search for.

### Returns
- `list[tuple[str, str, str]]` - List of tuples (pid, user, process_name).
```

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

### get_from_pince_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the path of the IPC file sent to custom gdb commands from PINCE for the given process ID.

```APIDOC
## get_from_pince_file(pid)

### Description
Get the path of IPC file sent to custom gdb commands from PINCE for given pid.

### Method
Function Call

### Signature
```python
libpince.utils.get_from_pince_file(pid: int | str) -> str
```

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

### Returns
- **str** - Path of IPC file.
```

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

### get_region_info(pid, address)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Finds the closest valid starting/ending address and region to given address, assuming given address is in the valid address range.

```APIDOC
## get_region_info(pid, address)

### Description
Finds the closest valid starting/ending address and region to given address, assuming given address is in the valid address range.

### Parameters
- **pid** (`int` | `str`) - Required - PID of the process
- **address** (`int` | `str`) - Required - Can be an int or a hex str

### Returns
- **tuple_region_info** (`tuple` | `None`) - List of (start_address, end_address, permissions, file_name) -> (int, int, str, str) None: If the given address isn’t in any valid address range
```

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

### get_logging_file(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the path to the gdb logfile for the given process ID.

```APIDOC
## get_logging_file(pid)

### Description
Get the path of gdb logfile of given pid.

### Method
Function Call

### Signature
```python
libpince.utils.get_logging_file(pid: int | str) -> str
```

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

### Returns
- **str** - Path of gdb logfile.
```

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

### get_effective_arch(pid)

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Returns the architecture of the code the debugged program actually executes, which can differ from the host process architecture, especially in WINE processes.

```APIDOC
## get_effective_arch(pid)

### Description
Returns the arch of the code the debugged program actually executes, unlike the arch of the host process. They can differ in WINE processes, particularly with New-WoW64 where 32 bits PE programs run inside a 64 bits host process.

### Method
Function Call

### Signature
```python
libpince.utils.get_effective_arch(pid: int) -> int
```

### Parameters
- **pid** (int) - Required - PID of the process

### Returns
- **int** - A member of typedefs.INFERIOR_ARCH, -1 if detection fails.
```

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

### get_module_load_bias(pid: int, name_regex: str) -> tuple[int, str] | None

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Function to find a module's load bias and path by name regex.

```APIDOC
## get_module_load_bias(pid: int, name_regex: str) -> tuple[int, str] | None

### Description
Finds the first mapped file whose basename matches the given regular expression and returns its load bias and absolute path.

### Parameters
- **pid** (int) - Required - PID of the process
- **name_regex** (str) - Required - Regular expression to match against the basename of mapped files

### Returns
- **tuple[int, str]** - `(load_bias, absolute_path)` where `load_bias` is an int and `absolute_path` is a str
- **None** - If no matching module is found
```

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

### instruction_follow_address(string)

Source: https://korcankaraokcu.github.io/PINCE/_modules/libpince/utils.html

Extracts the hex address from a location-changing assembly instruction (e.g., Jcc, CALL, LOOPcc).

```APIDOC
## instruction_follow_address(string)

### Description
Searches the given assembly expression for location-changing instructions and returns the hex address they jump to.

### Parameters
- **string** (str) - Required - An assembly expression.

### Returns
- **str** - Hex address if found.
- **None** - If no hex address is found or no location-changing instruction is present.
```

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

### save_file

Source: https://korcankaraokcu.github.io/PINCE/libpince.html

Saves data to a file using JSON or pickle serialization.

```APIDOC
## save_file(data, file_path, save_method='json')

### Description
Saves the specified data to the given path using either JSON or pickle serialization.

### Parameters
- **data** (`Any`) - Required - The data to save; must be supported by the chosen save method.
- **file_path** (`str`) - Required - Path of the file to save to.
- **save_method** (`str`) - Optional - Serialization method: "json" or "pickle". Defaults to "json".

### Returns
- `bool` - True if saved successfully, False otherwise.
```
Tokens:
Raw