ProxmoxVE/docs/misc/core.func/CORE_FUNCTIONS_REFERENCE.md

# core.func Functions Reference

## Overview

This document provides a comprehensive alphabetical reference of all functions in `core.func`, including parameters, dependencies, usage examples, and error handling.

## Function Categories

### Initialization Functions

#### `load_functions()`
**Purpose**: Main function loader that initializes all core utilities
**Parameters**: None
**Returns**: None
**Side Effects**:
- Sets `__FUNCTIONS_LOADED=1` to prevent reloading
- Calls all core function groups in sequence
- Initializes color, formatting, icons, defaults, and standard mode
**Dependencies**: None
**Environment Variables Used**: `__FUNCTIONS_LOADED`

**Usage Example**:
```bash
# Automatically called when core.func is sourced
source core.func
# load_functions() is called automatically
```

### Color and Formatting Functions

#### `color()`
**Purpose**: Set ANSI color codes for styled terminal output
**Parameters**: None
**Returns**: None
**Side Effects**: Sets global color variables
**Dependencies**: None
**Environment Variables Used**: None

**Sets Variables**:
- `YW`: Yellow
- `YWB`: Bright yellow
- `BL`: Blue
- `RD`: Red
- `BGN`: Bright green
- `GN`: Green
- `DGN`: Dark green
- `CL`: Clear/reset

**Usage Example**:
```bash
color
echo -e "${GN}Success message${CL}"
echo -e "${RD}Error message${CL}"
```

#### `color_spinner()`
**Purpose**: Set color codes specifically for spinner output
**Parameters**: None
**Returns**: None
**Side Effects**: Sets spinner-specific color variables
**Dependencies**: None
**Environment Variables Used**: None

**Sets Variables**:
- `CS_YW`: Yellow for spinner
- `CS_YWB`: Bright yellow for spinner
- `CS_CL`: Clear for spinner

#### `formatting()`
**Purpose**: Define formatting helpers for terminal output
**Parameters**: None
**Returns**: None
**Side Effects**: Sets global formatting variables
**Dependencies**: None
**Environment Variables Used**: None

**Sets Variables**:
- `BFR`: Back and forward reset
- `BOLD`: Bold text
- `HOLD`: Space character
- `TAB`: Two spaces
- `TAB3`: Six spaces

### Icon Functions

#### `icons()`
**Purpose**: Set symbolic icons used throughout user feedback and prompts
**Parameters**: None
**Returns**: None
**Side Effects**: Sets global icon variables
**Dependencies**: `formatting()` (for TAB variable)
**Environment Variables Used**: `TAB`, `CL`

**Sets Variables**:
- `CM`: Check mark
- `CROSS`: Cross mark
- `DNSOK`: DNS success
- `DNSFAIL`: DNS failure
- `INFO`: Information icon
- `OS`: Operating system icon
- `OSVERSION`: OS version icon
- `CONTAINERTYPE`: Container type icon
- `DISKSIZE`: Disk size icon
- `CPUCORE`: CPU core icon
- `RAMSIZE`: RAM size icon
- `SEARCH`: Search icon
- `VERBOSE_CROPPED`: Verbose mode icon
- `VERIFYPW`: Password verification icon
- `CONTAINERID`: Container ID icon
- `HOSTNAME`: Hostname icon
- `BRIDGE`: Bridge icon
- `NETWORK`: Network icon
- `GATEWAY`: Gateway icon
- `DISABLEIPV6`: IPv6 disable icon
- `DEFAULT`: Default settings icon
- `MACADDRESS`: MAC address icon
- `VLANTAG`: VLAN tag icon
- `ROOTSSH`: SSH key icon
- `CREATING`: Creating icon
- `ADVANCED`: Advanced settings icon
- `FUSE`: FUSE icon
- `HOURGLASS`: Hourglass icon

### Default Variables Functions

#### `default_vars()`
**Purpose**: Set default retry and wait variables for system actions
**Parameters**: None
**Returns**: None
**Side Effects**: Sets retry configuration variables
**Dependencies**: None
**Environment Variables Used**: None

**Sets Variables**:
- `RETRY_NUM`: Number of retry attempts (default: 10)
- `RETRY_EVERY`: Seconds between retries (default: 3)
- `i`: Retry counter initialized to RETRY_NUM

#### `set_std_mode()`
**Purpose**: Set default verbose mode for script execution
**Parameters**: None
**Returns**: None
**Side Effects**: Sets STD variable based on VERBOSE setting
**Dependencies**: None
**Environment Variables Used**: `VERBOSE`

**Sets Variables**:
- `STD`: "silent" if VERBOSE != "yes", empty string if VERBOSE = "yes"

### Silent Execution Functions

#### `silent()`
**Purpose**: Execute commands silently with detailed error reporting
**Parameters**: `$*` - Command and arguments to execute
**Returns**: None (exits on error)
**Side Effects**:
- Executes command with output redirected to log file
- On error, displays detailed error information
- Exits with command's exit code
**Dependencies**: `error_handler.func` (for error explanations)
**Environment Variables Used**: `SILENT_LOGFILE`

**Usage Example**:
```bash
silent apt-get update
silent apt-get install -y package-name
```

**Error Handling**:
- Captures command output to `/tmp/silent.$$.log`
- Shows error code explanation
- Displays last 10 lines of log
- Provides command to view full log

### System Check Functions

#### `shell_check()`
**Purpose**: Verify that the script is running in Bash shell
**Parameters**: None
**Returns**: None (exits if not Bash)
**Side Effects**:
- Checks current shell process
- Exits with error message if not Bash
**Dependencies**: None
**Environment Variables Used**: None

**Usage Example**:
```bash
shell_check
# Script continues if Bash, exits if not
```

#### `root_check()`
**Purpose**: Ensure script is running as root user
**Parameters**: None
**Returns**: None (exits if not root)
**Side Effects**:
- Checks user ID and parent process
- Exits with error message if not root
**Dependencies**: None
**Environment Variables Used**: None

**Usage Example**:
```bash
root_check
# Script continues if root, exits if not
```

#### `pve_check()`
**Purpose**: Verify Proxmox VE version compatibility
**Parameters**: None
**Returns**: None (exits if unsupported version)
**Side Effects**:
- Checks PVE version using pveversion command
- Exits with error message if unsupported
**Dependencies**: `pveversion` command
**Environment Variables Used**: None

**Supported Versions**:
- Proxmox VE 8.0 - 8.9
- Proxmox VE 9.0 (only)

**Usage Example**:
```bash
pve_check
# Script continues if supported version, exits if not
```

#### `arch_check()`
**Purpose**: Verify system architecture is AMD64
**Parameters**: None
**Returns**: None (exits if not AMD64)
**Side Effects**:
- Checks system architecture
- Exits with PiMox warning if not AMD64
**Dependencies**: `dpkg` command
**Environment Variables Used**: None

**Usage Example**:
```bash
arch_check
# Script continues if AMD64, exits if not
```

#### `ssh_check()`
**Purpose**: Detect and warn about external SSH usage
**Parameters**: None
**Returns**: None
**Side Effects**:
- Checks SSH_CLIENT environment variable
- Warns if connecting from external IP
- Allows local connections (127.0.0.1 or host IP)
**Dependencies**: None
**Environment Variables Used**: `SSH_CLIENT`

**Usage Example**:
```bash
ssh_check
# Shows warning if external SSH, continues anyway
```

### Header Management Functions

#### `get_header()`
**Purpose**: Download and cache application header files
**Parameters**: None (uses APP and APP_TYPE variables)
**Returns**: Header content on success, empty on failure
**Side Effects**:
- Downloads header from remote URL
- Caches header locally
- Creates directory structure if needed
**Dependencies**: `curl` command
**Environment Variables Used**: `APP`, `APP_TYPE`

**Usage Example**:
```bash
export APP="plex"
export APP_TYPE="ct"
header_content=$(get_header)
```

#### `header_info()`
**Purpose**: Display application header information
**Parameters**: None (uses APP variable)
**Returns**: None
**Side Effects**:
- Clears screen
- Displays header content
- Gets terminal width for formatting
**Dependencies**: `get_header()`, `tput` command
**Environment Variables Used**: `APP`

**Usage Example**:
```bash
export APP="plex"
header_info
# Displays Plex header information
```

### Utility Functions

#### `ensure_tput()`
**Purpose**: Ensure tput command is available for terminal control
**Parameters**: None
**Returns**: None
**Side Effects**:
- Installs ncurses package if tput missing
- Works on Alpine and Debian-based systems
**Dependencies**: `apk` or `apt-get` package managers
**Environment Variables Used**: None

**Usage Example**:
```bash
ensure_tput
# Installs ncurses if needed, continues if already available
```

#### `is_alpine()`
**Purpose**: Detect if running on Alpine Linux
**Parameters**: None
**Returns**: 0 if Alpine, 1 if not Alpine
**Side Effects**: None
**Dependencies**: None
**Environment Variables Used**: `var_os`, `PCT_OSTYPE`

**Usage Example**:
```bash
if is_alpine; then
    echo "Running on Alpine Linux"
else
    echo "Not running on Alpine Linux"
fi
```

#### `is_verbose_mode()`
**Purpose**: Check if verbose mode is enabled
**Parameters**: None
**Returns**: 0 if verbose mode, 1 if not verbose
**Side Effects**: None
**Dependencies**: None
**Environment Variables Used**: `VERBOSE`, `var_verbose`

**Usage Example**:
```bash
if is_verbose_mode; then
    echo "Verbose mode enabled"
else
    echo "Verbose mode disabled"
fi
```

#### `fatal()`
**Purpose**: Display fatal error and terminate script
**Parameters**: `$1` - Error message
**Returns**: None (terminates script)
**Side Effects**:
- Displays error message
- Sends INT signal to current process
**Dependencies**: `msg_error()`
**Environment Variables Used**: None

**Usage Example**:
```bash
fatal "Critical error occurred"
# Script terminates after displaying error
```

### Spinner Functions

#### `spinner()`
**Purpose**: Display animated spinner for progress indication
**Parameters**: None (uses SPINNER_MSG variable)
**Returns**: None (runs indefinitely)
**Side Effects**:
- Displays rotating spinner characters
- Uses terminal control sequences
**Dependencies**: `color_spinner()`
**Environment Variables Used**: `SPINNER_MSG`

**Usage Example**:
```bash
SPINNER_MSG="Processing..."
spinner &
SPINNER_PID=$!
# Spinner runs in background
```

#### `clear_line()`
**Purpose**: Clear current terminal line
**Parameters**: None
**Returns**: None
**Side Effects**: Clears current line using terminal control
**Dependencies**: `tput` command
**Environment Variables Used**: None

#### `stop_spinner()`
**Purpose**: Stop running spinner and cleanup
**Parameters**: None
**Returns**: None
**Side Effects**:
- Kills spinner process
- Removes PID file
- Resets terminal settings
- Unsets spinner variables
**Dependencies**: None
**Environment Variables Used**: `SPINNER_PID`, `SPINNER_MSG`

**Usage Example**:
```bash
stop_spinner
# Stops spinner and cleans up
```

### Message Functions

#### `msg_info()`
**Purpose**: Display informational message with spinner
**Parameters**: `$1` - Message text
**Returns**: None
**Side Effects**:
- Starts spinner if not in verbose mode
- Tracks shown messages to prevent duplicates
- Displays message with hourglass icon in verbose mode
**Dependencies**: `spinner()`, `is_verbose_mode()`, `is_alpine()`
**Environment Variables Used**: `MSG_INFO_SHOWN`

**Usage Example**:
```bash
msg_info "Installing package..."
# Shows spinner with message
```

#### `msg_ok()`
**Purpose**: Display success message
**Parameters**: `$1` - Success message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays green checkmark with message
- Removes message from shown tracking
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: `MSG_INFO_SHOWN`

**Usage Example**:
```bash
msg_ok "Package installed successfully"
# Shows green checkmark with message
```

#### `msg_error()`
**Purpose**: Display error message
**Parameters**: `$1` - Error message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays red cross with message
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: None

**Usage Example**:
```bash
msg_error "Installation failed"
# Shows red cross with message
```

#### `msg_warn()`
**Purpose**: Display warning message
**Parameters**: `$1` - Warning message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays yellow info icon with message
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: None

**Usage Example**:
```bash
msg_warn "This operation may take some time"
# Shows yellow info icon with message
```

#### `msg_custom()`
**Purpose**: Display custom message with specified symbol and color
**Parameters**:
- `$1` - Custom symbol (default: "[*]")
- `$2` - Color code (default: "\e[36m")
- `$3` - Message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays custom formatted message
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: None

**Usage Example**:
```bash
msg_custom "⚡" "\e[33m" "Custom warning message"
# Shows custom symbol and color with message
```

#### `msg_debug()`
**Purpose**: Display debug message if debug mode enabled
**Parameters**: `$*` - Debug message text
**Returns**: None
**Side Effects**:
- Only displays if var_full_verbose is set
- Shows timestamp and debug prefix
**Dependencies**: None
**Environment Variables Used**: `var_full_verbose`, `var_verbose`

**Usage Example**:
```bash
export var_full_verbose=1
msg_debug "Debug information here"
# Shows debug message with timestamp
```

### System Management Functions

#### `check_or_create_swap()`
**Purpose**: Check for active swap and optionally create swap file
**Parameters**: None
**Returns**: 0 if swap exists or created, 1 if skipped
**Side Effects**:
- Checks for active swap
- Prompts user to create swap if none found
- Creates swap file if user confirms
**Dependencies**: `swapon`, `dd`, `mkswap` commands
**Environment Variables Used**: None

**Usage Example**:
```bash
if check_or_create_swap; then
    echo "Swap is available"
else
    echo "No swap available"
fi
```

## Function Call Hierarchy

### Initialization Flow
```
load_functions()
├── color()
├── formatting()
├── icons()
├── default_vars()
└── set_std_mode()
```

### Message System Flow
```
msg_info()
├── is_verbose_mode()
├── is_alpine()
├── spinner()
└── color_spinner()

msg_ok()
├── stop_spinner()
└── clear_line()

msg_error()
└── stop_spinner()

msg_warn()
└── stop_spinner()
```

### System Check Flow
```
pve_check()
├── pveversion command
└── version parsing

arch_check()
├── dpkg command
└── architecture check

shell_check()
├── ps command
└── shell detection

root_check()
├── id command
└── parent process check
```

### Silent Execution Flow
```
silent()
├── Command execution
├── Output redirection
├── Error handling
├── error_handler.func loading
└── Log management
```

## Error Handling Patterns

### System Check Errors
- All system check functions exit with appropriate error messages
- Clear indication of what's wrong and how to fix it
- Graceful exit with sleep delay for user to read message

### Silent Execution Errors
- Commands executed via `silent()` capture output to log file
- On failure, displays error code explanation
- Shows last 10 lines of log output
- Provides command to view full log

### Spinner Errors
- Spinner functions handle process cleanup on exit
- Trap handlers ensure spinners are stopped
- Terminal settings are restored on error

## Environment Variable Dependencies

### Required Variables
- `APP`: Application name for header display
- `APP_TYPE`: Application type (ct/vm) for header paths
- `VERBOSE`: Verbose mode setting

### Optional Variables
- `var_os`: OS type for Alpine detection
- `PCT_OSTYPE`: Alternative OS type variable
- `var_verbose`: Alternative verbose setting
- `var_full_verbose`: Debug mode setting

### Internal Variables
- `_CORE_FUNC_LOADED`: Prevents multiple loading
- `__FUNCTIONS_LOADED`: Prevents multiple function loading
- `SILENT_LOGFILE`: Silent execution log file path
- `SPINNER_PID`: Spinner process ID
- `SPINNER_MSG`: Spinner message text
- `MSG_INFO_SHOWN`: Tracks shown info messages