⚙️ The command-line flags available More...

Files
file	acds.c
	ACDS mode option parsing and help text.

file	acds.h
	ACDS (Discovery Service) mode option parsing.

file	actions.c
	Action option callbacks for ascii-chat.

file	actions.h
	Action option callbacks for ascii-chat.

file	builder.c
	Implementation of options builder API.

file	builder.h
	Options builder API for flexible command-line option configuration.

file	client.c
	Client mode option parsing and help text.

file	client.h
	Client mode option parsing.

file	common.c
	Common utilities and helpers for option parsing.

file	common.h
	Common utilities and helpers for option parsing.

file	levenshtein.h
	Levenshtein distance algorithm for fuzzy string matching.

file	mirror.c
	Mirror mode option parsing and help text.

file	mirror.h
	Mirror mode option parsing.

file	options.c
	⚙️ Unified command-line argument parser with built-in mode detection

file	options.h
	⚙️ Command-line options parsing and configuration management for ascii-chat

file	parsers.c
	Custom option parsers implementation.

file	parsers.h
	Custom option parsers for enum types.

file	presets.c
	Preset option configurations for ascii-chat modes.

file	server.c
	Server mode option parsing and help text.

file	server.h
	Server mode option parsing.

file	validation.h
	Validation functions for options parsing.

Data Structures
struct	options_state
	Consolidated options structure. More...

Macros
#define	LEVENSHTEIN_SUGGESTION_THRESHOLD 3
	Maximum edit distance to suggest an option.

#define	COLOR_MODE_AUTO TERM_COLOR_AUTO
	Backward compatibility aliases for color mode enum values.

#define	COLOR_MODE_NONE TERM_COLOR_NONE
	Monochrome mode.

#define	COLOR_MODE_16 TERM_COLOR_16
	16-color mode (alias)

#define	COLOR_MODE_16_COLOR TERM_COLOR_16
	16-color mode (full name)

#define	COLOR_MODE_256 TERM_COLOR_256
	256-color mode (alias)

#define	COLOR_MODE_256_COLOR TERM_COLOR_256
	256-color mode (full name)

#define	COLOR_MODE_TRUECOLOR TERM_COLOR_TRUECOLOR
	24-bit truecolor mode

#define	ASCIICHAT_BINARY_OPTIONS_STRUCT
	Binary-level options (parsed before mode selection)

#define	ASCIICHAT_COMMON_OPTIONS_STRUCT
	Common options (all modes after binary parsing)

#define	ASCIICHAT_SERVER_OPTIONS_STRUCT
	Server mode options.

#define	ASCIICHAT_CLIENT_OPTIONS_STRUCT
	Client mode options.

#define	ASCIICHAT_MIRROR_OPTIONS_STRUCT
	Mirror mode options.

#define	ASCIICHAT_ACDS_OPTIONS_STRUCT
	ACDS mode options.

#define	GET_OPTION(field)
	Safely get a specific option field (lock-free read)

Typedefs
typedef struct options_state	options_t
	Consolidated options structure.

Enumerations
enum	asciichat_mode_t { MODE_SERVER , MODE_CLIENT , MODE_MIRROR , MODE_ACDS }
	Mode type for options parsing. More...

Functions
ASCIICHAT_API size_t	levenshtein (const char a, const char b)
	Calculate Levenshtein distance between two strings.

ASCIICHAT_API size_t	levenshtein_n (const char a, const size_t length, const char b, const size_t bLength)
	Calculate Levenshtein distance with explicit string lengths.

ASCIICHAT_API const char *	levenshtein_find_similar (const char unknown, const char const *candidates)
	Find the most similar string from a NULL-terminated array.

const options_t *	options_get (void)
	Get current options (lock-free read)

asciichat_error_t	options_update (void(updater)(options_t , void ), void context)
	Update options using copy-on-write (thread-safe)

asciichat_error_t	options_set_dimensions (unsigned short int width, unsigned short int height)
	Update terminal dimensions.

asciichat_error_t	options_set_color_mode (terminal_color_mode_t mode)
	Update color mode.

asciichat_error_t	options_set_render_mode (render_mode_t mode)
	Update render mode.

asciichat_error_t	options_set_log_level (log_level_t level)
	Update log level.

Variables
ASCIICHAT_API int	opt_acds_port
	TCP listen port (ACDS mode only)

ASCIICHAT_API char	opt_acds_database_path [OPTIONS_BUFF_SIZE]
	SQLite database path (ACDS mode only)

ASCIICHAT_API char	opt_acds_key_path [OPTIONS_BUFF_SIZE]
	Ed25519 identity key path (ACDS mode only)

const float	weight_red

const float	weight_green
	Green weight for luminance calculation.

const float	weight_blue
	Blue weight for luminance calculation.

unsigned short int	RED []
	Red channel lookup table.

unsigned short int	GREEN []
	Green channel lookup table.

unsigned short int	BLUE []
	Blue channel lookup table.

unsigned short int	GRAY []
	Grayscale lookup table.

Utility Functions
int	strtoint_safe (const char *str)
	Safely parse string to integer with validation.

Option Parsing Functions
asciichat_error_t	options_init (int argc, char **argv)
	Initialize options by parsing command-line arguments.

void	usage (FILE *desc, asciichat_mode_t mode)
	Print usage information for client, server, or mirror mode.

void	usage_client (FILE *desc)
	Print client usage information.

void	usage_server (FILE *desc)
	Print server usage information.

void	usage_mirror (FILE *desc)
	Print mirror usage information.

void	usage_acds (FILE *desc)
	Print ACDS usage information.

Dimension Update Functions
void	update_dimensions_for_full_height (options_t *opts)
	Update dimensions for full height display.

void	update_dimensions_to_terminal_size (options_t *opts)
	Update dimensions to match terminal size.

Validation Functions
ASCIICHAT_API int	validate_opt_port (const char value_str, char error_msg, size_t error_msg_size)
	Validate port number (1-65535)

ASCIICHAT_API int	validate_opt_positive_int (const char value_str, char error_msg, size_t error_msg_size)
	Validate positive integer.

ASCIICHAT_API int	validate_opt_non_negative_int (const char value_str, char error_msg, size_t error_msg_size)
	Validate non-negative integer.

ASCIICHAT_API int	validate_opt_color_mode (const char value_str, char error_msg, size_t error_msg_size)
	Validate color mode string.

ASCIICHAT_API int	validate_opt_render_mode (const char value_str, char error_msg, size_t error_msg_size)
	Validate render mode string.

ASCIICHAT_API int	validate_opt_palette (const char value_str, char error_msg, size_t error_msg_size)
	Validate palette type string.

ASCIICHAT_API int	validate_opt_log_level (const char value_str, char error_msg, size_t error_msg_size)
	Validate log level string.

ASCIICHAT_API int	validate_opt_ip_address (const char value_str, char parsed_address, size_t address_size, bool is_client, char *error_msg, size_t error_msg_size)
	Validate IP address or hostname.

ASCIICHAT_API float	validate_opt_float_non_negative (const char value_str, char error_msg, size_t error_msg_size)
	Validate non-negative float value.

ASCIICHAT_API int	validate_opt_fps (const char value_str, char error_msg, size_t error_msg_size)
	Validate FPS value (1-144)

ASCIICHAT_API int	validate_opt_max_clients (const char value_str, char error_msg, size_t error_msg_size)
	Validate max clients value (1-32)

ASCIICHAT_API int	validate_opt_compression_level (const char value_str, char error_msg, size_t error_msg_size)
	Validate compression level (1-9)

ASCIICHAT_API int	validate_opt_reconnect (const char value_str, char error_msg, size_t error_msg_size)
	Validate reconnect value.

ASCIICHAT_API int	validate_opt_device_index (const char value_str, char error_msg, size_t error_msg_size)
	Validate device index (-1 for default, 0+ for specific device)

ASCIICHAT_API int	validate_opt_password (const char value_str, char error_msg, size_t error_msg_size)
	Validate password (8-256 characters)

Configuration Constants
#define	OPTIONS_BUFF_SIZE 256
	Buffer size for option string values.

#define	OPT_WIDTH_DEFAULT 110
	Default terminal width in characters.

#define	OPT_HEIGHT_DEFAULT 70
	Default terminal height in characters.

#define	SNAPSHOT_DELAY_DEFAULT 3.0f
	Default snapshot delay in seconds.

#define	OPT_PORT_DEFAULT "27224"
	Default TCP port for client/server communication.

#define	OPT_ADDRESS_DEFAULT "localhost"
	Default server address for client connections.

#define	OPT_ADDRESS6_DEFAULT "::1"
	Default IPv6 server address.

#define	OPT_MAX_CLIENTS_DEFAULT 9
	Default maximum concurrent clients (server only)

#define	OPT_COMPRESSION_LEVEL_DEFAULT 1
	Default compression level (1-9)

#define	OPT_FPS_DEFAULT 60
	Default FPS (frames per second)

#define	OPT_WEBCAM_INDEX_DEFAULT 0
	Default webcam device index.

#define	OPT_MICROPHONE_INDEX_DEFAULT (-1)
	Default microphone device index (-1 means system default)

#define	OPT_SPEAKERS_INDEX_DEFAULT (-1)
	Default speakers device index (-1 means system default)

#define	OPT_RECONNECT_ATTEMPTS_DEFAULT (-1)
	Default reconnect attempts (-1 means auto/infinite)

#define	OPT_WEBCAM_FLIP_DEFAULT true
	Default webcam flip state (true = horizontally flipped)

#define	OPT_COLOR_MODE_DEFAULT COLOR_MODE_AUTO
	Default color mode (auto-detect terminal capabilities)

#define	OPT_RENDER_MODE_DEFAULT RENDER_MODE_FOREGROUND
	Default render mode (foreground characters only)

#define	OPT_ENCODE_AUDIO_DEFAULT true
	Default audio encoding state (true = Opus encoding enabled)

Detailed Description

⚙️ The command-line flags available

This header provides comprehensive functionality for parsing command-line arguments and managing configuration settings for both client and server modes of ascii-chat. It serves as the central configuration system, parsing user preferences and providing defaults for all application settings.

Design Philosophy:

The options system follows a global configuration pattern where all options are stored in global variables that can be accessed throughout the application. This design:

Simplifies access: No need to pass configuration objects around
Single source of truth: Options are parsed once at startup
Validation at parse time: Invalid options are rejected immediately
Sensible defaults: All options have reasonable default values
Mode-aware: Different options for client vs server modes

Option Categories:

Options are organized into logical categories:

Terminal Dimensions: Width, height, auto-detection
Network Configuration: Server address, port, IPv4/IPv6
Webcam Settings: Device index, flip, test pattern
Display Options: Color mode, render mode, UTF-8, capabilities
Audio Configuration: Audio enable/disable, device selection
Image Options: Aspect ratio preservation, stretching
Output Options: Quiet mode, snapshot mode, log file
Encryption Options: Key files, passwords, client/server keys
Palette Configuration: Palette type, custom characters, luminance weights

Option Parsing:

Options are parsed using the standard POSIX getopt() interface (with Windows compatibility via platform/windows/getopt.h). The parser:

Supports both short (-w 80) and long (--width 80) option formats
Validates option values (e.g., numeric ranges, file existence)
Provides helpful error messages for invalid options
Prints usage information for --help
Handles mode-specific options (client vs server)

Default Values:

All options have sensible defaults that work out-of-the-box:

Terminal dimensions: Auto-detect from terminal size
Network: localhost:27224 (IPv4)
Webcam: First available device (index 0)
Color mode: Auto-detect terminal capabilities
Encryption: Disabled by default (can be enabled with --key or --password)

Option Lifecycle:

Initialization: Call options_init() at program startup
Parsing: options_init() parses command-line arguments
Validation: Options are validated and defaults applied
Usage: Access option values via global variables throughout the application
Updates: Some options can be updated dynamically (e.g., terminal dimensions)

Usage Example:

#include "options.h"
 
int main(int argc, char **argv) {
    // Parse command-line options
    asciichat_error_t err = options_init(argc, argv, true);  // is_client = true
    if (err != ASCIICHAT_OK) {
        if (err == ERROR_USAGE) {
            usage(stderr, true);  // Print usage and exit
        }
        return 1;
    }
 
    // Access parsed options
    printf("Connecting to %s:%s\n", opt_address, opt_port);
    printf("Terminal size: %dx%d\n", opt_width, opt_height);
    if (opt_encrypt_enabled) {
        printf("Encryption enabled\n");
    }
 
    // Use options throughout application
    // ...
 
    return 0;
}

Command-Line Options:

Common options (see usage() function for complete list):

--width, -w: Set terminal width in characters
--height, -h: Set terminal height in characters
--address, -a: Bind address (server only)
--port, -p: Server port (or override positional argument port for client)
--key, -k: SSH key file path for encryption
--password: Password for authentication
--color, --256, --truecolor: Force color mode
--palette: Select ASCII palette
--help: Print usage information and exit

Client address syntax (positional argument, not option flag):

ascii-chat client → connects to localhost:27224
ascii-chat client example.com → connects to example.com:27224
ascii-chat client 192.168.1.1:8080 → connects to 192.168.1.1:8080
ascii-chat client [::1]:8080 → connects to IPv6 [::1]:8080

Thread Safety:

Options are parsed once at startup in the main thread before any worker threads are created. After parsing, options are effectively read-only (with some exceptions for dynamic updates like terminal dimensions). Therefore, thread safety is not a concern for most options. If options need to be modified at runtime, ensure proper synchronization.

Option Validation:

The parser validates:

Numeric ranges (e.g., webcam index must be >= 0)
File existence (e.g., key files, log files)
Format correctness (e.g., IP addresses, port numbers)
Mode compatibility (some options are client-only or server-only)

Invalid options result in ERROR_USAGE being returned, and usage information is printed to help the user correct their command line.

Note: All options are stored as global variables. This is intentional for simplicity.; Options are parsed once at startup via options_init().; Most options remain constant after parsing (read-only).; Some options (e.g., terminal dimensions) can be updated dynamically.

See also: options_init() for option parsing; usage() for usage information; platform/terminal.h for terminal capability detection; palette.h for Character Palettes configuration

Author: Zachary Fogg me@zf.nosp@m.o.gg

Date: September 2025

This header provides validation functions used during command-line option parsing and configuration file loading. These functions validate user input and provide detailed error messages for invalid values.

All validation functions follow a consistent pattern:

Return 0 or positive value on success (often the parsed value)
Return -1 or negative value on error
Write error messages to the provided error_msg buffer

Note: These functions are used by both options.c and config.c

Options README

Overview

The Options system provides command-line argument parsing support for ascii-chat. It handles server and client options, validates settings, and manages application configuration.

Implementation: lib/options.h, lib/config.h

Key Features:

Command-line argument parsing with getopt
Server and client mode options
Automatic help generation
Configuration validation
Default value management

Operation Modes

Server Mode:

./ascii-chat server [options]

Client Mode:

./ascii-chat client [options]

Common Options

Network Options:

[address][:port] (positional for client) - Server address with optional port (default: localhost:27224)
[address1] [address2] (positional for server) - Bind addresses, 0-2 IPv4/IPv6 addresses
--port PORT - Server port (default: 27224)

Display Options:

--width WIDTH - Terminal width (default: auto-detect)
--height HEIGHT - Terminal height (default: auto-detect)
--color - Enable color output
--stretch - Stretch video to fill terminal
--half-block - Use half-block rendering (2x vertical resolution)

Video Options:

--webcam INDEX - Webcam device index (default: 0)
--webcam-flip - Flip webcam horizontally
--test-pattern - Use test pattern instead of webcam
--snapshot - Capture single frame and exit
--snapshot-delay SEC - Delay before snapshot (default: 1.0)

Audio Options:

--audio - Enable audio (client only, server always has audio)
--no-audio - Disable audio

Crypto Options:

--key PATH - SSH private key for authentication
--server-key KEY - Server public key or github:username
--password PASS - Shared password for encryption
--insecure - Skip host identity verification (NOT RECOMMENDED)
--client-keys KEYS - Whitelist of allowed client keys (comma-separated)

Logging Options:

--log-file PATH - Write logs to file
--log-level LEVEL - Set log level (0-4)

Configuration Options:

--config PATH - Load configuration from TOML file
--config-create [PATH] - Create default config file and exit

Usage Examples

Server Examples

Basic Server:

./ascii-chat server

Server with Authentication:

./ascii-chat server --key ~/.ssh/id_ed25519 --client-keys github:user1,github:user2

Server with Custom Port:

./ascii-chat server --port 8080

Server with Logging:

./ascii-chat server --log-file /var/log/ascii-chat.log --log-level 1

Client Examples

Basic Client:

./ascii-chat client

Connect to Remote Server:

./ascii-chat client 192.168.1.100:27224

Client with Audio and Color:

./ascii-chat client --audio --color

Client with Custom Webcam:

./ascii-chat client --webcam 1 --webcam-flip

Snapshot Mode:

./ascii-chat client --snapshot --snapshot-delay 5

Client with Server Verification:

./ascii-chat client --server-key github:zfogg

Programmatic API

Parse Options:

options_t opts;
asciichat_error_t err = parse_options(argc, argv, &opts);
if (err != ASCIICHAT_OK) {
    return err;
}

Error Handling:

asciichat_error_t err = parse_options(argc, argv, &opts);
if (err != ASCIICHAT_OK) {
    asciichat_error_context_t ctx;
    if (HAS_ERRNO(&ctx)) {
        log_error("Invalid options: %s", ctx.context_message);
    }
    return err;
}

Help System

Show Help:

./ascii-chat --help
./ascii-chat server --help
./ascii-chat client --help

Help Output:

Lists all available options
Shows default values
Provides usage examples
Displays mode-specific options

See also: Configuration for configuration files and precedence; options.h; config.h

Macro Definition Documentation

◆ ASCIICHAT_ACDS_OPTIONS_STRUCT

#define ASCIICHAT_ACDS_OPTIONS_STRUCT

#include <options.h>

Value:

  ASCIICHAT_COMMON_OPTIONS_STRUCT                                                                                      \
  char address[OPTIONS_BUFF_SIZE];                                                                                     \
  char port[OPTIONS_BUFF_SIZE];                                                                                        \
  unsigned short int require_server_identity;                                                                          \
  unsigned short int require_client_identity;                                                                          \
  unsigned short int require_server_verify;                                                                            \
  unsigned short int require_client_verify;                                                                            \
  char stun_servers[OPTIONS_BUFF_SIZE];                                                                                \
  char turn_servers[OPTIONS_BUFF_SIZE];                                                                                \
  char turn_username[OPTIONS_BUFF_SIZE];                                                                               \
  char turn_credential[OPTIONS_BUFF_SIZE];                                                                             \
  char turn_secret[OPTIONS_BUFF_SIZE];

ACDS mode options.

Complete set of options for ACDS (discovery service) mode.

Definition at line 407 of file options.h.

             {
  MODE_SERVER, 
  MODE_CLIENT, 
  MODE_MIRROR, 
  MODE_ACDS    
} asciichat_mode_t;
 
typedef struct options_state {
  // ============================================================================
  // Mode Detection (auto-detected during options_init)
  // ============================================================================
  asciichat_mode_t detected_mode; 
 
  // ============================================================================
  // Binary-Level Options (parsed first, before mode selection)
  // ============================================================================
  bool help;    
  bool version; 
 
  // ============================================================================
  // Terminal Dimensions
  // ============================================================================
  unsigned short int width;  
  unsigned short int height; 
  bool auto_width;           
  bool auto_height;          
 
  // ============================================================================
  // Network Options
  // ============================================================================
  char address[OPTIONS_BUFF_SIZE];  
  char address6[OPTIONS_BUFF_SIZE]; 
  char port[OPTIONS_BUFF_SIZE];     
  int max_clients;                  
  char session_string[64];          
 
  // ============================================================================
  // ACDS Discovery Options (server only)
  // ============================================================================
  bool acds;                                  
  char acds_server[OPTIONS_BUFF_SIZE];        
  int acds_port;                              
  bool webrtc;                                
  char acds_key_path[OPTIONS_BUFF_SIZE];      
  char acds_database_path[OPTIONS_BUFF_SIZE]; 
 
  // ============================================================================
  // LAN Discovery Options
  // ============================================================================
  bool lan_discovery;     
  bool no_mdns_advertise; 
 
  // ============================================================================
  // Network Performance Options
  // ============================================================================
  int compression_level; 
  bool no_compress;      
  bool encode_audio;     
 
  // ============================================================================
  // Client Reconnection Options
  // ============================================================================
  int reconnect_attempts; 
 
  // ============================================================================
  // Webcam Options
  // ============================================================================
  unsigned short int webcam_index; 
  bool webcam_flip;                
  bool test_pattern;               
  bool no_audio_mixer;             
 
  // ============================================================================
  // Display Options
  // ============================================================================
  terminal_color_mode_t color_mode;     
  render_mode_t render_mode;            
  unsigned short int show_capabilities; 
  unsigned short int force_utf8;        
  int fps;                              
 
  // ============================================================================
  // Audio Configuration
  // ============================================================================
  unsigned short int audio_enabled;          
  int microphone_index;                      
  int speakers_index;                        
  unsigned short int audio_analysis_enabled; 
  unsigned short int audio_no_playback;      
 
  // ============================================================================
  // Image Options
  // ============================================================================
  unsigned short int stretch; 
 
  // ============================================================================
  // Output Options
  // ============================================================================
  unsigned short int quiet;         
  unsigned short int verbose_level; 
  unsigned short int snapshot_mode; 
  double snapshot_delay;            
  unsigned short int strip_ansi;    
  char log_file[OPTIONS_BUFF_SIZE]; 
  log_level_t log_level;            
 
  // ============================================================================
  // Encryption Options
  // ============================================================================
  unsigned short int encrypt_enabled;      
  char encrypt_key[OPTIONS_BUFF_SIZE];     
  char password[OPTIONS_BUFF_SIZE];        
  char encrypt_keyfile[OPTIONS_BUFF_SIZE]; 
  unsigned short int no_encrypt;           
  char server_key[OPTIONS_BUFF_SIZE];      
  char client_keys[OPTIONS_BUFF_SIZE];     
 
  // ============================================================================
  // Identity Verification Options (ACDS + Crypto Handshake)
  // ============================================================================
  bool require_server_identity; 
  bool require_client_identity; 
  bool require_server_verify;   
  bool require_client_verify;   
  bool acds_expose_ip;          
  bool acds_insecure;           
 
  // ============================================================================
  // WebRTC Connection Strategy Options (client-side fallback control)
  // ============================================================================
  bool prefer_webrtc;       
  bool no_webrtc;           
  bool webrtc_skip_stun;    
  bool webrtc_disable_turn; 
 
  // ============================================================================
  // WebRTC Connectivity Options (ACDS mode only)
  // ============================================================================
  bool enable_upnp;                        
  bool no_upnp;                            
  char stun_servers[OPTIONS_BUFF_SIZE];    
  char turn_servers[OPTIONS_BUFF_SIZE];    
  char turn_username[OPTIONS_BUFF_SIZE];   
  char turn_credential[OPTIONS_BUFF_SIZE]; 
  char turn_secret[OPTIONS_BUFF_SIZE];     
 
  // ============================================================================
  // Palette Configuration
  // ============================================================================
  palette_type_t palette_type; 
  char palette_custom[256];    
  bool palette_custom_set;     
 
  // Note: Luminance weights (weight_red, weight_green, weight_blue) and
  // lookup tables (RED[], GREEN[], BLUE[], GRAY[]) are kept as globals
  // since they're precomputed constants, not user-configurable options.
} options_t;
 
// ============================================================================
// RCU-based thread-safe options access
// ============================================================================
 
const options_t *options_get(void);
 
#define GET_OPTION(field)                                                                                              \
  ({                                                                                                                   \
    const options_t *_opts = options_get();                                                                            \
    if (!_opts) {                                                                                                      \
      log_warn("GET_OPTION(" #field ") called but options not initialized");                                           \
    }                                                                                                                  \
    static typeof(((options_t *)0)->field) _default = {0};                                                             \
    (_opts ? (_opts->field) : _default);                                                                               \
  })
 
asciichat_error_t options_update(void (*updater)(options_t *, void *), void *context);
 
asciichat_error_t options_set_dimensions(unsigned short int width, unsigned short int height);
 
asciichat_error_t options_set_color_mode(terminal_color_mode_t mode);
 
asciichat_error_t options_set_render_mode(render_mode_t mode);
 
asciichat_error_t options_set_log_level(log_level_t level);
 
static inline unsigned short int options_get_width(void) {
  return options_get()->width;
}
 
static inline unsigned short int options_get_height(void) {
  return options_get()->height;
}
 
extern const float weight_red;
 
extern const float weight_green;
 
extern const float weight_blue;
 
extern unsigned short int RED[];
 
extern unsigned short int GREEN[];
 
extern unsigned short int BLUE[];
 
extern unsigned short int GRAY[];
 
asciichat_error_t options_init(int argc, char **argv);
 
void usage(FILE *desc, asciichat_mode_t mode);
 
void usage_client(FILE *desc);
 
void usage_server(FILE *desc);
 
void usage_mirror(FILE *desc);
 
void usage_acds(FILE *desc);
 
void update_dimensions_for_full_height(options_t *opts);
 
void update_dimensions_to_terminal_size(options_t *opts);
 

◆ ASCIICHAT_BINARY_OPTIONS_STRUCT

#define ASCIICHAT_BINARY_OPTIONS_STRUCT

#include <options.h>

Value:

  bool help;                                                                                                           \
  bool version;                                                                                                        \
  char log_file[OPTIONS_BUFF_SIZE];                                                                                    \
  log_level_t log_level;                                                                                               \
  unsigned short int quiet;                                                                                            \
  unsigned short int verbose_level;

Binary-level options (parsed before mode selection)

These options are common to all modes and parsed first.

Definition at line 311 of file options.h.

◆ ASCIICHAT_CLIENT_OPTIONS_STRUCT

#define ASCIICHAT_CLIENT_OPTIONS_STRUCT

#include <options.h>

Value:

  ASCIICHAT_COMMON_OPTIONS_STRUCT                                                                                      \
  char address[OPTIONS_BUFF_SIZE];                                                                                     \
  char port[OPTIONS_BUFF_SIZE];                                                                                        \
  int reconnect_attempts;                                                                                              \
  unsigned short int webcam_index;                                                                                     \
  bool webcam_flip;                                                                                                    \
  bool test_pattern;                                                                                                   \
  terminal_color_mode_t color_mode;                                                                                    \
  render_mode_t render_mode;                                                                                           \
  unsigned short int show_capabilities;                                                                                \
  unsigned short int force_utf8;                                                                                       \
  unsigned short int audio_enabled;                                                                                    \
  int microphone_index;                                                                                                \
  int speakers_index;                                                                                                  \
  unsigned short int stretch;                                                                                          \
  unsigned short int snapshot_mode;                                                                                    \
  double snapshot_delay;                                                                                               \
  char server_key[OPTIONS_BUFF_SIZE];                                                                                  \
  char encrypt_key[OPTIONS_BUFF_SIZE];                                                                                 \
  char password[OPTIONS_BUFF_SIZE];                                                                                    \
  unsigned short int require_client_verify;

Client mode options.

Complete set of options for client mode.

Definition at line 364 of file options.h.

◆ ASCIICHAT_COMMON_OPTIONS_STRUCT

#define ASCIICHAT_COMMON_OPTIONS_STRUCT

#include <options.h>

Value:

  ASCIICHAT_BINARY_OPTIONS_STRUCT                                                                                      \
  unsigned short int width;                                                                                            \
  unsigned short int height;                                                                                           \
  bool auto_width;                                                                                                     \
  bool auto_height;

Common options (all modes after binary parsing)

These options extend binary options with terminal dimensions.

Definition at line 324 of file options.h.

◆ ASCIICHAT_MIRROR_OPTIONS_STRUCT

#define ASCIICHAT_MIRROR_OPTIONS_STRUCT

#include <options.h>

Value:

  ASCIICHAT_COMMON_OPTIONS_STRUCT                                                                                      \
  unsigned short int webcam_index;                                                                                     \
  bool webcam_flip;                                                                                                    \
  bool test_pattern;                                                                                                   \
  terminal_color_mode_t color_mode;                                                                                    \
  render_mode_t render_mode;                                                                                           \
  unsigned short int force_utf8;                                                                                       \
  unsigned short int stretch;

Mirror mode options.

Complete set of options for mirror mode (local webcam viewing).

Definition at line 392 of file options.h.

◆ ASCIICHAT_SERVER_OPTIONS_STRUCT

#define ASCIICHAT_SERVER_OPTIONS_STRUCT

#include <options.h>

Value:

  ASCIICHAT_COMMON_OPTIONS_STRUCT                                                                                      \
  char address[OPTIONS_BUFF_SIZE];                                                                                     \
  char address6[OPTIONS_BUFF_SIZE];                                                                                    \
  char port[OPTIONS_BUFF_SIZE];                                                                                        \
  int max_clients;                                                                                                     \
  int compression_level;                                                                                               \
  bool no_compress;                                                                                                    \
  bool encode_audio;                                                                                                   \
  unsigned short int encrypt_enabled;                                                                                  \
  char encrypt_key[OPTIONS_BUFF_SIZE];                                                                                 \
  char password[OPTIONS_BUFF_SIZE];                                                                                    \
  char encrypt_keyfile[OPTIONS_BUFF_SIZE];                                                                             \
  unsigned short int no_encrypt;                                                                                       \
  char client_keys[OPTIONS_BUFF_SIZE];                                                                                 \
  unsigned short int require_server_verify;                                                                            \
  bool acds;           /* Enable ACDS session registration (default: false) */                                         \
  bool acds_expose_ip; /* Explicitly allow public IP disclosure in ACDS sessions (opt-in) */                           \
  bool acds_insecure;  /* Skip server key verification (MITM-vulnerable, requires explicit opt-in) */                  \
  char acds_server[OPTIONS_BUFF_SIZE];                                                                                 \
  int acds_port;                                                                                                       \
  bool webrtc; /* Enable WebRTC mode for ACDS session (default: Direct TCP) */

Server mode options.

Complete set of options for server mode.

Definition at line 336 of file options.h.

◆ COLOR_MODE_16

#define COLOR_MODE_16 TERM_COLOR_16

#include <options.h>

16-color mode (alias)

Definition at line 158 of file options.h.

◆ COLOR_MODE_16_COLOR

#define COLOR_MODE_16_COLOR TERM_COLOR_16

#include <options.h>

16-color mode (full name)

Definition at line 159 of file options.h.

◆ COLOR_MODE_256

#define COLOR_MODE_256 TERM_COLOR_256

#include <options.h>

256-color mode (alias)

Definition at line 160 of file options.h.

◆ COLOR_MODE_256_COLOR

#define COLOR_MODE_256_COLOR TERM_COLOR_256

#include <options.h>

256-color mode (full name)

Definition at line 161 of file options.h.

◆ COLOR_MODE_AUTO

#define COLOR_MODE_AUTO TERM_COLOR_AUTO

#include <options.h>

Backward compatibility aliases for color mode enum values.

Auto-detect color support

Definition at line 156 of file options.h.

◆ COLOR_MODE_NONE

#define COLOR_MODE_NONE TERM_COLOR_NONE

#include <options.h>

Monochrome mode.

Definition at line 157 of file options.h.

◆ COLOR_MODE_TRUECOLOR

#define COLOR_MODE_TRUECOLOR TERM_COLOR_TRUECOLOR

#include <options.h>

24-bit truecolor mode

Definition at line 162 of file options.h.

◆ GET_OPTION

#define GET_OPTION ( field )

#include <options.h>

Value:

  ({                                                                                                                   \
    const options_t *_opts = options_get();                                                                            \
    if (!_opts) {                                                                                                      \
      log_warn("GET_OPTION(" #field ") called but options not initialized");                                           \
    }                                                                                                                  \
    static typeof(((options_t *)0)->field) _default = {0};                                                             \
    (_opts ? (_opts->field) : _default);                                                                               \
  })

Safely get a specific option field (lock-free read)

Convenience macro for accessing individual option fields without storing the entire options pointer. Includes NULL check with warning log for safety.

Usage Examples:

// Simple field access
const char *addr = GET_OPTION(address6);
int width = GET_OPTION(width);
bool flip = GET_OPTION(webcam_flip);
 
// In expressions
if (GET_OPTION(encrypt_enabled)) {
    // encryption is enabled
}
 
// Function arguments
connect_to_server(GET_OPTION(address), GET_OPTION(port));

Design: This macro eliminates the need to store const options_t *opts pointers around the codebase, reducing clutter and making code more readable.

Safety: If options_get() returns NULL (shouldn't happen after initialization), the macro will log a warning and return a zero-initialized field.

Performance: Equivalent cost to direct options_get()->field access.

Parameters

field The field name to access (e.g., address, port, width, etc.)

Returns: The value of the requested field

Note: Must be called after options_init() has completed; Zero-initialized fields are returned if options pointer is somehow NULL

Definition at line 644 of file options.h.

   {                                                                                                                   \
    const options_t *_opts = options_get();                                                                            \
    if (!_opts) {                                                                                                      \
      log_warn("GET_OPTION(" #field ") called but options not initialized");                                           \
    }                                                                                                                  \
    static typeof(((options_t *)0)->field) _default = {0};                                                             \
    (_opts ? (_opts->field) : _default);                                                                               \
  })

◆ LEVENSHTEIN_SUGGESTION_THRESHOLD

#define LEVENSHTEIN_SUGGESTION_THRESHOLD 3

#include <levenshtein.h>

Maximum edit distance to suggest an option.

Threshold of 2 catches most typos (single char errors, transpositions) without suggesting unrelated options.

Definition at line 29 of file levenshtein.h.

◆ OPT_ADDRESS6_DEFAULT

#define OPT_ADDRESS6_DEFAULT "::1"

#include <options.h>

Default IPv6 server address.

Definition at line 222 of file options.h.

◆ OPT_ADDRESS_DEFAULT

#define OPT_ADDRESS_DEFAULT "localhost"

#include <options.h>

Default server address for client connections.

Definition at line 219 of file options.h.

◆ OPT_COLOR_MODE_DEFAULT

#define OPT_COLOR_MODE_DEFAULT COLOR_MODE_AUTO

#include <options.h>

Default color mode (auto-detect terminal capabilities)

Definition at line 249 of file options.h.

◆ OPT_COMPRESSION_LEVEL_DEFAULT

#define OPT_COMPRESSION_LEVEL_DEFAULT 1

#include <options.h>

Default compression level (1-9)

Definition at line 228 of file options.h.

◆ OPT_ENCODE_AUDIO_DEFAULT

#define OPT_ENCODE_AUDIO_DEFAULT true

#include <options.h>

Default audio encoding state (true = Opus encoding enabled)

Definition at line 255 of file options.h.

◆ OPT_FPS_DEFAULT

#define OPT_FPS_DEFAULT 60

#include <options.h>

Default FPS (frames per second)

Definition at line 231 of file options.h.

◆ OPT_HEIGHT_DEFAULT

#define OPT_HEIGHT_DEFAULT 70

#include <options.h>

Default terminal height in characters.

Default height used when terminal size cannot be detected or when auto-detection is disabled. This default provides a reasonable size for ASCII art display.

Note: This is used as a fallback if --height is not specified and auto-detection fails.

Definition at line 198 of file options.h.

◆ OPT_MAX_CLIENTS_DEFAULT

#define OPT_MAX_CLIENTS_DEFAULT 9

#include <options.h>

Default maximum concurrent clients (server only)

Definition at line 225 of file options.h.

◆ OPT_MICROPHONE_INDEX_DEFAULT

#define OPT_MICROPHONE_INDEX_DEFAULT (-1)

#include <options.h>

Default microphone device index (-1 means system default)

Definition at line 237 of file options.h.

◆ OPT_PORT_DEFAULT

#define OPT_PORT_DEFAULT "27224"

#include <options.h>

Default TCP port for client/server communication.

Definition at line 216 of file options.h.

◆ OPT_RECONNECT_ATTEMPTS_DEFAULT

#define OPT_RECONNECT_ATTEMPTS_DEFAULT (-1)

#include <options.h>

Default reconnect attempts (-1 means auto/infinite)

Definition at line 243 of file options.h.

◆ OPT_RENDER_MODE_DEFAULT

#define OPT_RENDER_MODE_DEFAULT RENDER_MODE_FOREGROUND

#include <options.h>

Default render mode (foreground characters only)

Definition at line 252 of file options.h.

◆ OPT_SPEAKERS_INDEX_DEFAULT

#define OPT_SPEAKERS_INDEX_DEFAULT (-1)

#include <options.h>

Default speakers device index (-1 means system default)

Definition at line 240 of file options.h.

◆ OPT_WEBCAM_FLIP_DEFAULT

#define OPT_WEBCAM_FLIP_DEFAULT true

#include <options.h>

Default webcam flip state (true = horizontally flipped)

Definition at line 246 of file options.h.

◆ OPT_WEBCAM_INDEX_DEFAULT

#define OPT_WEBCAM_INDEX_DEFAULT 0

#include <options.h>

Default webcam device index.

Definition at line 234 of file options.h.

◆ OPT_WIDTH_DEFAULT

#define OPT_WIDTH_DEFAULT 110

#include <options.h>

Default terminal width in characters.

Default width used when terminal size cannot be detected or when auto-detection is disabled. This default provides a reasonable size for ASCII art display.

Note: This is used as a fallback if --width is not specified and auto-detection fails.

Definition at line 187 of file options.h.

◆ OPTIONS_BUFF_SIZE

#define OPTIONS_BUFF_SIZE 256

#include <options.h>

Buffer size for option string values.

Maximum size for string-based options (e.g., addresses, file paths, passwords). Used for arrays that store option values.

Definition at line 176 of file options.h.

◆ SNAPSHOT_DELAY_DEFAULT

#define SNAPSHOT_DELAY_DEFAULT 3.0f

#include <options.h>

Default snapshot delay in seconds.

Default delay for snapshot mode before exiting. macOS webcams show pure black first then fade up into a real color image over a few seconds, so we use a longer delay on macOS.

Definition at line 212 of file options.h.

Typedef Documentation

◆ options_t

typedef struct options_state options_t

#include <options.h>

Consolidated options structure.

All options from the scattered extern globals are now in a single struct. This struct is immutable once published via RCU - modifications create a new copy.

Enumeration Type Documentation

◆ asciichat_mode_t

enum asciichat_mode_t

#include <options.h>

Mode type for options parsing.

Determines which set of options to use when parsing command-line arguments.

Enumerator
MODE_SERVER	Server mode - network server options.
MODE_CLIENT	Client mode - network client options.
MODE_MIRROR	Mirror mode - local webcam viewing (no network)
MODE_ACDS	Discovery service mode - session management and WebRTC signaling.

Definition at line 426 of file options.h.

             {
  MODE_SERVER, 
  MODE_CLIENT, 
  MODE_MIRROR, 
  MODE_ACDS    
} asciichat_mode_t;

Function Documentation

◆ levenshtein()

ASCIICHAT_API size_t levenshtein	(	const char *	a,
		const char *	b
	)

#include <levenshtein.h>

Calculate Levenshtein distance between two strings.

The Levenshtein distance is the minimum number of single-character edits (insertions, deletions, or substitutions) required to change one string into the other.

Parameters

a	First string
b	Second string

Returns: Edit distance, or SIZE_MAX on error

See also: https://en.wikipedia.org/wiki/Levenshtein_distance

Definition at line 72 of file levenshtein.c.

                                                 {
  if (!a || !b) {
    return SIZE_MAX;
  }
  const size_t length = strlen(a);
  const size_t bLength = strlen(b);
 
  return levenshtein_n(a, length, b, bLength);
}

References levenshtein_n().

Referenced by find_similar_option(), and levenshtein_find_similar().

◆ levenshtein_find_similar()

ASCIICHAT_API const char * levenshtein_find_similar	(	const char *	unknown,
		const char const	candidates
	)

#include <levenshtein.h>

Find the most similar string from a NULL-terminated array.

Searches through an array of candidate strings to find the one most similar to the input string, using Levenshtein distance.

Parameters

unknown	The string to match against
candidates	NULL-terminated array of candidate strings

Returns: Best matching string, or NULL if no match within threshold

Definition at line 82 of file levenshtein.c.

                                                                                         {
  if (!unknown || !candidates) {
    return NULL;
  }
 
  const char *best_match = NULL;
  size_t best_distance = SIZE_MAX;
 
  for (int i = 0; candidates[i] != NULL; i++) {
    size_t dist = levenshtein(unknown, candidates[i]);
    if (dist < best_distance) {
      best_distance = dist;
      best_match = candidates[i];
    }
  }
 
  // Only suggest if the distance is within our threshold
  if (best_distance <= LEVENSHTEIN_SUGGESTION_THRESHOLD) {
    return best_match;
  }
 
  return NULL;
}

References levenshtein(), and LEVENSHTEIN_SUGGESTION_THRESHOLD.

◆ levenshtein_n()

ASCIICHAT_API size_t levenshtein_n	(	const char *	a,
		const size_t	length,
		const char *	b,
		const size_t	bLength
	)

#include <levenshtein.h>

Calculate Levenshtein distance with explicit string lengths.

Parameters

a	First string
length	Length of first string
b	Second string
bLength	Length of second string

Returns: Edit distance, or SIZE_MAX on error

Definition at line 20 of file levenshtein.c.

                                                                                              {
  // Shortcut optimizations / degenerate cases.
  if (a == b) {
    return 0;
  }
 
  if (length == 0) {
    return bLength;
  }
 
  if (bLength == 0) {
    return length;
  }
 
  size_t *cache = SAFE_CALLOC(length, sizeof(size_t), size_t *);
  if (!cache) {
    return SIZE_MAX; // Allocation failed
  }
 
  size_t index = 0;
  size_t bIndex = 0;
  size_t distance;
  size_t bDistance;
  size_t result = 0;
  char code;
 
  // initialize the vector.
  while (index < length) {
    cache[index] = index + 1;
    index++;
  }
 
  // Loop.
  while (bIndex < bLength) {
    code = b[bIndex];
    result = distance = bIndex++;
 
    for (index = 0; index < length; index++) {
      bDistance = code == a[index] ? distance : distance + 1;
      distance = cache[index];
 
      cache[index] = result = distance > result      ? bDistance > result ? result + 1 : bDistance
                              : bDistance > distance ? distance + 1
                                                     : bDistance;
    }
  }
 
  SAFE_FREE(cache);
 
  return result;
}

References SAFE_CALLOC, and SAFE_FREE.

Referenced by levenshtein().

◆ options_get()

const options_t * options_get ( void )

#include <options.h>

Get current options (lock-free read)

Returns a pointer to the current options struct. This pointer is guaranteed to remain valid for the lifetime of your function (no one will free it under you).

Performance: Single atomic pointer load (~1-2ns on modern CPUs)

Returns: Pointer to current options (never NULL after options_init())

Definition at line 222 of file rcu.c.

                                   {
  // Lock-free read with acquire semantics
  // Guarantees we see all writes made before the pointer was published
  options_t *current = atomic_load_explicit(&g_options, memory_order_acquire);
 
  // Should never be NULL after initialization
  if (!current) {
    log_fatal("Options not initialized! Call options_state_init() first");
    log_warn("options_get() called before options initialization - this will cause a crash");
    abort();
  }
 
  return current;
}

References log_fatal, and log_warn.

Referenced by asciichat_shared_init(), client_crypto_init(), client_main(), log_set_terminal_output(), main(), main(), server_crypto_handshake(), tcp_client_send_terminal_capabilities(), and threaded_send_terminal_size_with_auto_detect().

◆ options_init()

asciichat_error_t options_init	(	int	argc,
		char **	argv
	)

#include <options.h>

Initialize options by parsing command-line arguments.

Parameters

argc	Argument count from main()
argv	Argument vector from main()
is_client	true if parsing client options, false for server options

Returns: ASCIICHAT_OK on success, ERROR_USAGE on parse errors

Parses command-line arguments and initializes all option global variables. This function must be called once at program startup before accessing any options.

Parsing Process:

Parse command-line arguments using getopt() (POSIX-compliant)
Validate option values (ranges, file existence, formats)
Apply default values for unspecified options
Perform mode-specific validation (client vs server)
Initialize global option variables

Special Return Values:

ASCIICHAT_OK: Parsing succeeded (normal case)
ASCIICHAT_OK: Also returned for --help and --version (after printing info)
ERROR_USAGE: Parse error or invalid option (usage info should be printed)

Mode-Specific Behavior:

Client mode (is_client = true): Parses client-specific options (color mode, webcam, snapshot mode, etc.)
Server mode (is_client = false): Parses server-specific options (bind address, client keys whitelist, etc.)

Validation:

Numeric ranges (e.g., port 1-65535, webcam index >= 0)
File existence (key files, log files)
Format correctness (IP addresses, port numbers)
Mode compatibility (rejects client-only options in server mode)

Default Value Application: After parsing, unspecified options are set to defaults:

Terminal dimensions: Auto-detect or use OPT_WIDTH_DEFAULT/OPT_HEIGHT_DEFAULT
Network: localhost:27224
Webcam: Index 0 (first device)
Color mode: Auto-detect
Encryption: Enabled if keys found, disabled otherwise

Environment Variables: The following environment variables are checked during option parsing:

WEBCAM_DISABLED: When set to "1", "true", "yes", or "on", automatically enables test pattern mode (opt_test_pattern = true). Useful for CI/CD environments and testing without a physical webcam.

Example:: int main(int argc, char **argv) {

// Parse options (client mode)

asciichat_error_t err = options_init(argc, argv, true);

if (err != ASCIICHAT_OK) {

if (err == ERROR_USAGE) {

usage(stderr, true); // Print usage

}

return 1;

}

// Options are now available via global variables

printf("Connecting to %s:%s\n", opt_address, opt_port);

return 0;

}

Note: Must be called once at program startup before accessing options; Global option variables are initialized by this function; Returns ERROR_USAGE for invalid options (caller should print usage); --help and --version cause early exit (function still returns ASCIICHAT_OK)

Initialize options by parsing command-line arguments with unified mode detection

Parameters

argc	Argument count from main()
argv	Argument vector from main()

Returns: ASCIICHAT_OK on success, ERROR_USAGE on parse errors

Unified options initialization that handles:

Mode detection from argv (or defaults to server)
Binary-level option parsing (–help, –version, –log-file, etc.)
Mode-specific option parsing
Configuration file loading
Post-processing and validation

The detected mode is stored in options_t->detected_mode for retrieval via options_get()->detected_mode after this function returns.

Mode Detection Priority:

–help or –version → handled internally, may exit(0)
First non-option positional argument → matched against mode names
Session string pattern (word-word-word) → treated as client mode
No mode specified → defaults to show help and exit(0)

Note: Must be called once at program startup before accessing options; Global option variables are initialized by this function; Returns ERROR_USAGE for invalid options (after printing error); –help and –version may exit directly (returns ASCIICHAT_OK if they print first)

Definition at line 144 of file options.c.

                                                      {
  // Validate arguments (safety check for tests)
  if (argc < 0 || argc > 1000) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid argc: %d", argc);
  }
  if (argv == NULL) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "argv is NULL");
  }
  // Validate all argv elements are non-NULL up to argc
  for (int i = 0; i < argc; i++) {
    if (argv[i] == NULL) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "argv[%d] is NULL (argc=%d)", i, argc);
    }
  }
 
  // Initialize RCU options system (must be done before any threads start)
  asciichat_error_t rcu_init_result = options_state_init();
  if (rcu_init_result != ASCIICHAT_OK) {
    return rcu_init_result;
  }
 
  // Create local options struct and initialize with defaults
  options_t opts = {0}; // Zero-initialize all fields
 
  // ========================================================================
  // STAGE 1: Mode Detection and Binary-Level Option Handling
  // ========================================================================
 
  asciichat_mode_t detected_mode = MODE_SERVER; // Default mode
  char detected_session_string[64] = {0};
  int mode_index = -1;
 
  // First, detect the mode from command-line arguments
  asciichat_error_t mode_detect_result =
      options_detect_mode(argc, argv, &detected_mode, detected_session_string, &mode_index);
  if (mode_detect_result != ASCIICHAT_OK) {
    return mode_detect_result;
  }
 
  opts.detected_mode = detected_mode;
 
  // Check for binary-level --help, --version, or --config-create
  // These only trigger if:
  // 1. No mode was detected (mode_index == -1), OR
  // 2. The option appears BEFORE the mode in argv
  bool show_help = false;
  bool show_version = false;
  bool create_config = false;
  const char *config_create_path = NULL;
 
  int search_limit = (mode_index == -1) ? argc : mode_index;
  for (int i = 1; i < search_limit; i++) {
    if (argv[i][0] == '-') {
      if (strcmp(argv[i], "--help") == 0 || strcmp(argv[i], "-h") == 0) {
        show_help = true;
        break;
      }
      if (strcmp(argv[i], "--version") == 0 || strcmp(argv[i], "-v") == 0) {
        show_version = true;
        break;
      }
      if (strcmp(argv[i], "--config-create") == 0) {
        create_config = true;
        // Check if next argument is a path (not a flag)
        if (i + 1 < argc && argv[i + 1][0] != '-') {
          config_create_path = argv[i + 1];
        }
        break;
      }
    }
  }
 
  if (show_help) {
    // Show binary-level help from src/main.c
    opts.help = true;
    options_state_set(&opts);
    return ASCIICHAT_OK;
  }
 
  if (show_version) {
    // Show binary-level version from src/main.c
    opts.version = true;
    options_state_set(&opts);
    return ASCIICHAT_OK;
  }
 
  if (create_config) {
    // Handle --config-create: create default config file and exit
    // Use provided path or default to user config location
    char config_path[PLATFORM_MAX_PATH_LENGTH];
    if (config_create_path) {
      SAFE_STRNCPY(config_path, config_create_path, sizeof(config_path));
    } else {
      // Use default config path: ~/.ascii-chat/config.toml
      char *config_dir = get_config_dir();
      if (!config_dir) {
        fprintf(stderr, "Error: Failed to determine default config directory\n");
        return ERROR_CONFIG;
      }
      snprintf(config_path, sizeof(config_path), "%sconfig.toml", config_dir);
      SAFE_FREE(config_dir);
    }
 
    // Create config with default options
    asciichat_error_t result = config_create_default(config_path, &opts);
    if (result != ASCIICHAT_OK) {
      asciichat_error_context_t err_ctx;
      if (HAS_ERRNO(&err_ctx)) {
        fprintf(stderr, "Error creating config: %s\n", err_ctx.context_message);
      } else {
        fprintf(stderr, "Error: Failed to create config file at %s\n", config_path);
      }
      return result;
    }
 
    printf("Created default config file at: %s\n", config_path);
    exit(0); // Exit successfully after creating config
  }
 
  // ========================================================================
  // STAGE 2: Build argv for mode-specific parsing
  // ========================================================================
 
  // If mode was found, build argv with only arguments after the mode
  // If mode_index == -1, we use all arguments (they become mode-specific args)
  int mode_argc = argc;
  char **mode_argv = (char **)argv;
 
  if (mode_index != -1) {
    // Mode found at position mode_index
    // Build new argv: [program_name, args_before_mode..., args_after_mode...]
    // This preserves binary-level options like --log-file that appear before mode
 
    // Special case: if mode_index == 0, argv[0] is the mode name (test compatibility)
    // Use "ascii-chat" as the binary name
    int args_before_mode = (mode_index == 0) ? 0 : (mode_index - 1);
    int args_after_mode = argc - mode_index - 1;
    mode_argc = 1 + args_before_mode + args_after_mode;
 
    if (mode_argc > 256) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "Too many arguments: %d", mode_argc);
    }
 
    // Allocate mode_argc+1 to accommodate NULL terminator
    char **new_mode_argv = SAFE_MALLOC((size_t)(mode_argc + 1) * sizeof(char *), char **);
    if (!new_mode_argv) {
      return SET_ERRNO(ERROR_MEMORY, "Failed to allocate mode_argv");
    }
 
    // Copy: [program_name, args_before_mode..., args_after_mode...]
    if (mode_index == 0) {
      // Mode is at argv[0], use "ascii-chat" as program name
      new_mode_argv[0] = "ascii-chat";
    } else {
      new_mode_argv[0] = argv[0];
    }
    for (int i = 0; i < args_before_mode; i++) {
      new_mode_argv[1 + i] = argv[1 + i]; // argv[1] to argv[mode_index-1]
    }
    for (int i = 0; i < args_after_mode; i++) {
      new_mode_argv[1 + args_before_mode + i] = argv[mode_index + 1 + i];
    }
    new_mode_argv[mode_argc] = NULL;
 
    mode_argv = new_mode_argv;
  }
 
  // ========================================================================
  // STAGE 3: Set Mode-Specific Defaults
  // ========================================================================
 
  // Set default dimensions (fallback if terminal size detection fails)
  opts.width = OPT_WIDTH_DEFAULT;
  opts.height = OPT_HEIGHT_DEFAULT;
  opts.auto_width = true;
  opts.auto_height = true;
 
  // Set default port
  SAFE_SNPRINTF(opts.port, OPTIONS_BUFF_SIZE, "%s", OPT_PORT_DEFAULT);
 
  // Set other non-zero defaults (using macros from options.h)
  opts.webcam_flip = OPT_WEBCAM_FLIP_DEFAULT;
  opts.color_mode = OPT_COLOR_MODE_DEFAULT;
  opts.render_mode = OPT_RENDER_MODE_DEFAULT;
  opts.encode_audio = OPT_ENCODE_AUDIO_DEFAULT;
  opts.compression_level = OPT_COMPRESSION_LEVEL_DEFAULT;
  opts.max_clients = OPT_MAX_CLIENTS_DEFAULT;
  opts.microphone_index = OPT_MICROPHONE_INDEX_DEFAULT;
  opts.speakers_index = OPT_SPEAKERS_INDEX_DEFAULT;
  opts.reconnect_attempts = OPT_RECONNECT_ATTEMPTS_DEFAULT;
 
  // Set default log file paths based on build type
  // Release: $tmpdir/ascii-chat/MODE.log (e.g., /tmp/ascii-chat/server.log)
  // Debug: MODE.log in current working directory (e.g., ./server.log)
  char *log_dir = get_log_dir();
  if (log_dir) {
    // Determine log filename based on mode
    const char *log_filename;
    switch (detected_mode) {
    case MODE_SERVER:
      log_filename = "server.log";
      break;
    case MODE_CLIENT:
      log_filename = "client.log";
      break;
    case MODE_MIRROR:
      log_filename = "mirror.log";
      break;
    case MODE_ACDS:
      log_filename = "acds.log";
      break;
    default:
      log_filename = "ascii-chat.log";
      break;
    }
 
    // Build full log file path: log_dir + separator + log_filename
    char default_log_path[PLATFORM_MAX_PATH_LENGTH];
    safe_snprintf(default_log_path, sizeof(default_log_path), "%s%s%s", log_dir, PATH_SEPARATOR_STR, log_filename);
 
    // Validate and normalize the path
    char *normalized_default_log = NULL;
    if (path_validate_user_path(default_log_path, PATH_ROLE_LOG_FILE, &normalized_default_log) == ASCIICHAT_OK) {
      SAFE_SNPRINTF(opts.log_file, OPTIONS_BUFF_SIZE, "%s", normalized_default_log);
      SAFE_FREE(normalized_default_log);
    } else {
      // Validation failed - use the path as-is (validation may fail in debug builds)
      SAFE_SNPRINTF(opts.log_file, OPTIONS_BUFF_SIZE, "%s", default_log_path);
    }
 
    SAFE_FREE(log_dir);
  } else {
    // Fallback if get_log_dir() fails - use simple filename in CWD
    const char *log_filename;
    switch (detected_mode) {
    case MODE_SERVER:
      log_filename = "server.log";
      break;
    case MODE_CLIENT:
      log_filename = "client.log";
      break;
    case MODE_MIRROR:
      log_filename = "mirror.log";
      break;
    case MODE_ACDS:
      log_filename = "acds.log";
      break;
    default:
      log_filename = "ascii-chat.log";
      break;
    }
    SAFE_SNPRINTF(opts.log_file, OPTIONS_BUFF_SIZE, "%s", log_filename);
  }
 
  // Encryption options default to disabled/empty
  opts.no_encrypt = 0;
  opts.encrypt_key[0] = '\0';
  opts.password[0] = '\0';
  opts.encrypt_keyfile[0] = '\0';
  opts.server_key[0] = '\0';
  opts.client_keys[0] = '\0';
  opts.palette_custom[0] = '\0';
 
  // Set different default addresses for different modes
  if (detected_mode == MODE_CLIENT || detected_mode == MODE_MIRROR) {
    // Client/Mirror: connects to localhost by default
    SAFE_SNPRINTF(opts.address, OPTIONS_BUFF_SIZE, "localhost");
    opts.address6[0] = '\0'; // Client doesn't use address6
  } else if (detected_mode == MODE_SERVER) {
    // Server: binds to 127.0.0.1 (IPv4) and ::1 (IPv6) by default
    SAFE_SNPRINTF(opts.address, OPTIONS_BUFF_SIZE, "127.0.0.1");
    // address6 is now a positional argument, not an option
    opts.address6[0] = '\0';
  } else if (detected_mode == MODE_ACDS) {
    // ACDS: binds to all interfaces by default
    SAFE_SNPRINTF(opts.address, OPTIONS_BUFF_SIZE, "0.0.0.0");
    opts.address6[0] = '\0';
  }
 
  // ========================================================================
  // STAGE 4: Load Configuration Files
  // ========================================================================
 
  bool is_client_or_mirror = (detected_mode == MODE_CLIENT || detected_mode == MODE_MIRROR);
  asciichat_error_t config_result = config_load_system_and_user(is_client_or_mirror, NULL, false, &opts);
  (void)config_result; // Continue with defaults and CLI parsing regardless of result
 
  // ========================================================================
  // STAGE 5: Parse Command-Line Arguments (Mode-Specific)
  // ========================================================================
 
  asciichat_error_t result = ASCIICHAT_OK;
  switch (detected_mode) {
  case MODE_SERVER:
    result = parse_server_options(mode_argc, mode_argv, &opts);
    break;
  case MODE_CLIENT:
    result = parse_client_options(mode_argc, mode_argv, &opts);
    break;
  case MODE_MIRROR:
    result = parse_mirror_options(mode_argc, mode_argv, &opts);
    break;
  case MODE_ACDS:
    result = parse_acds_options(mode_argc, mode_argv, &opts);
    break;
  default:
    result = SET_ERRNO(ERROR_INVALID_PARAM, "Invalid detected mode: %d", detected_mode);
  }
 
  // Free the temporary mode_argv if we allocated it
  if (mode_argv != (char **)argv) {
    SAFE_FREE(mode_argv);
  }
 
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  // Set session string if it was detected (ACDS mode via session string pattern)
  if (detected_session_string[0] != '\0') {
    SAFE_STRNCPY(opts.session_string, detected_session_string, sizeof(opts.session_string));
  }
 
  // ========================================================================
  // STAGE 6: Post-Processing & Validation
  // ========================================================================
 
  // After parsing command line options, update dimensions
  // First set any auto dimensions to terminal size, then apply full height logic
  update_dimensions_to_terminal_size(&opts);
  update_dimensions_for_full_height(&opts);
 
  // Apply verbose level to log threshold
  // Each -V decreases the log level by 1 (showing more verbose output)
  // Minimum level is LOG_DEV (0)
  if (opts.verbose_level > 0) {
    log_level_t current_level = log_get_level();
    int new_level = (int)current_level - (int)opts.verbose_level;
    if (new_level < LOG_DEV) {
      new_level = LOG_DEV;
    }
    log_set_level((log_level_t)new_level);
  }
 
  // Check WEBCAM_DISABLED environment variable to enable test pattern mode
  // Useful for CI/CD and testing environments without a physical webcam
  const char *webcam_disabled = SAFE_GETENV("WEBCAM_DISABLED");
  if (webcam_disabled &&
      (strcmp(webcam_disabled, "1") == 0 || platform_strcasecmp(webcam_disabled, "true") == 0 ||
       platform_strcasecmp(webcam_disabled, "yes") == 0 || platform_strcasecmp(webcam_disabled, "on") == 0)) {
    opts.test_pattern = true;
  }
 
  // Apply --no-compress interaction with audio encoding
  if (opts.no_compress) {
    opts.encode_audio = false;
    log_debug("--no-compress set: disabling audio encoding");
  }
 
  // ========================================================================
  // STAGE 7: Publish to RCU
  // ========================================================================
 
  // Publish parsed options to RCU state (replaces options_state_populate_from_globals)
  // This makes the options visible to all threads via lock-free reads
  asciichat_error_t publish_result = options_state_set(&opts);
  if (publish_result != ASCIICHAT_OK) {
    log_error("Failed to publish parsed options to RCU state");
    return publish_result;
  }
 
  return ASCIICHAT_OK;
}

References options_state::address, options_state::address6, ASCIICHAT_OK, options_state::auto_height, options_state::auto_width, options_state::client_keys, options_state::color_mode, options_state::compression_level, config_create_default(), config_load_system_and_user(), asciichat_error_context_t::context_message, options_state::detected_mode, options_state::encode_audio, options_state::encrypt_key, options_state::encrypt_keyfile, ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_MEMORY, get_config_dir(), get_log_dir(), HAS_ERRNO, options_state::height, options_state::help, log_debug, LOG_DEV, log_error, options_state::log_file, log_get_level(), log_set_level(), options_state::max_clients, options_state::microphone_index, MODE_ACDS, MODE_CLIENT, MODE_MIRROR, MODE_SERVER, options_state::no_compress, options_state::no_encrypt, OPT_COLOR_MODE_DEFAULT, OPT_COMPRESSION_LEVEL_DEFAULT, OPT_ENCODE_AUDIO_DEFAULT, OPT_HEIGHT_DEFAULT, OPT_MAX_CLIENTS_DEFAULT, OPT_MICROPHONE_INDEX_DEFAULT, OPT_PORT_DEFAULT, OPT_RECONNECT_ATTEMPTS_DEFAULT, OPT_RENDER_MODE_DEFAULT, OPT_SPEAKERS_INDEX_DEFAULT, OPT_WEBCAM_FLIP_DEFAULT, OPT_WIDTH_DEFAULT, OPTIONS_BUFF_SIZE, options_state_init(), options_state_set(), options_state::palette_custom, parse_acds_options(), parse_client_options(), parse_mirror_options(), parse_server_options(), options_state::password, PATH_ROLE_LOG_FILE, PATH_SEPARATOR_STR, path_validate_user_path(), PLATFORM_MAX_PATH_LENGTH, platform_strcasecmp(), options_state::port, options_state::reconnect_attempts, options_state::render_mode, SAFE_FREE, SAFE_GETENV, SAFE_MALLOC, SAFE_SNPRINTF, safe_snprintf(), SAFE_STRNCPY, options_state::server_key, options_state::session_string, SET_ERRNO, options_state::speakers_index, options_state::test_pattern, update_dimensions_for_full_height(), update_dimensions_to_terminal_size(), options_state::verbose_level, options_state::version, options_state::webcam_flip, and options_state::width.

Referenced by main(), and main().

◆ options_set_color_mode()

asciichat_error_t options_set_color_mode ( terminal_color_mode_t mode )

#include <options.h>

Update color mode.

Thread-safe setter for color mode. Uses RCU update internally.

Parameters

mode	New color mode

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 304 of file rcu.c.

                                                                     {
  return options_update(color_mode_updater, &mode);
}

References options_update().

◆ options_set_dimensions()

asciichat_error_t options_set_dimensions	(	unsigned short int	width,
		unsigned short int	height
	)

#include <options.h>

Update terminal dimensions.

Thread-safe setter for width/height. Uses RCU update internally.

Parameters

width	New terminal width in characters
height	New terminal height in characters

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 294 of file rcu.c.

                                                                                              {
  struct dimensions_update_ctx ctx = {.width = width, .height = height};
  return options_update(dimensions_updater, &ctx);
}

References dimensions_update_ctx::height, options_update(), and dimensions_update_ctx::width.

◆ options_set_log_level()

asciichat_error_t options_set_log_level ( log_level_t level )

#include <options.h>

Update log level.

Thread-safe setter for log level. Uses RCU update internally.

Parameters

level New log level

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 322 of file rcu.c.

                                                           {
  return options_update(log_level_updater, &level);
}

References options_update().

◆ options_set_render_mode()

asciichat_error_t options_set_render_mode ( render_mode_t mode )

#include <options.h>

Update render mode.

Thread-safe setter for render mode. Uses RCU update internally.

Parameters

mode	New render mode

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 313 of file rcu.c.

                                                              {
  return options_update(render_mode_updater, &mode);
}

References options_update().

◆ options_update()

asciichat_error_t options_update	(	void()(options_t , void *)	updater,
		void *	context
	)

#include <options.h>

Update options using copy-on-write (thread-safe)

Callback-based update interface. Allocates a new options struct, copies current values, calls your callback to modify the copy, then atomically swaps the global pointer.

Thread Safety: Multiple writers are serialized with a mutex. Readers are never blocked.

Parameters

updater	Callback function that modifies the new options struct
context	User context pointer passed to callback (can be NULL)

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 237 of file rcu.c.

                                                                                      {
  if (!updater) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "updater function is NULL");
  }
 
  if (!g_options_initialized) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Options state not initialized");
  }
 
  // Serialize writers with mutex
  mutex_lock(&g_options_write_mutex);
 
  // 1. Load current options (acquire semantics)
  options_t *old_opts = atomic_load_explicit(&g_options, memory_order_acquire);
 
  // 2. Allocate new options struct
  options_t *new_opts = SAFE_MALLOC(sizeof(options_t), options_t *);
  if (!new_opts) {
    mutex_unlock(&g_options_write_mutex);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate new options struct");
  }
 
  // 3. Copy current values to new struct
  memcpy(new_opts, old_opts, sizeof(options_t));
 
  // 4. Call user updater to modify the new struct
  updater(new_opts, context);
 
  // 5. Atomically swap global pointer (release semantics)
  // This makes the new struct visible to all readers
  atomic_store_explicit(&g_options, new_opts, memory_order_release);
 
  // 6. Add old struct to deferred free list
  deferred_free_add(old_opts);
 
  mutex_unlock(&g_options_write_mutex);
 
  log_debug("Options updated via RCU (old=%p, new=%p)", (void *)old_opts, (void *)new_opts);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, log_debug, mutex_lock, mutex_unlock, SAFE_MALLOC, and SET_ERRNO.

Referenced by main(), options_set_color_mode(), options_set_dimensions(), options_set_log_level(), and options_set_render_mode().

◆ strtoint_safe()

int strtoint_safe ( const char * str )

#include <options.h>

Safely parse string to integer with validation.

Parameters

str	String to parse (must not be NULL)

Returns: Integer value on success, INT_MIN on error

Parses a string to an integer with comprehensive validation:

Validates that string is not NULL or empty
Performs base-10 conversion using strtol()
Checks for partial conversions (characters left unconverted)
Validates result is within int range (INT_MIN to INT_MAX)
Returns INT_MIN on any error condition

This function is used internally by the options parser to safely convert command-line argument strings to integer values with proper error handling.

Note: Returns INT_MIN on error (which is distinguishable from valid negative values since INT_MIN is a valid integer, but unlikely to be used as an option value). The options parser checks for INT_MIN to detect parse errors.; Thread-safe: Uses only local variables, no static state.

Example:: const char *arg = "80";

int width = strtoint_safe(arg);

if (width == INT_MIN) {

// Parse error

} else {

// Valid integer: width == 80

}

strtoint_safe
int strtoint_safe(const char *str)
Safely parse string to integer with validation.
Definition options/common.c:67

Parses a string to integer using parse_int32() with full range checking. Returns INT_MIN on error (NULL input, empty string, invalid format, out of range).

Parameters

str	String to parse

Returns: Parsed integer value, or INT_MIN on error

Warning: INT_MIN is used as error sentinel, so cannot represent INT_MIN value

Example:

int val = strtoint_safe(optarg);
if (val == INT_MIN) {
    fprintf(stderr, "Invalid integer: %s\n", optarg);
    return ERROR_INVALID_PARAM;
}

Definition at line 67 of file options/common.c.

                                   {
  if (!str || *str == '\0') {
    return INT_MIN; // Error: NULL or empty string
  }
 
  int32_t result = 0;
  // Use safe parsing utility with full int32 range validation
  if (parse_int32(str, &result, INT_MIN, INT_MAX) != ASCIICHAT_OK) {
    return INT_MIN; // Error: invalid input or out of range
  }
 
  return (int)result;
}

References ASCIICHAT_OK, and parse_int32().

Referenced by client_crypto_init(), server_main(), validate_fps_opt(), validate_opt_compression_level(), validate_opt_device_index(), validate_opt_fps(), validate_opt_max_clients(), validate_opt_non_negative_int(), validate_opt_positive_int(), validate_opt_reconnect(), and validate_positive_int_opt().

◆ update_dimensions_for_full_height()

void update_dimensions_for_full_height ( options_t * opts )

#include <options.h>

Update dimensions for full height display.

Adjusts opt_width and opt_height to use the full terminal height while maintaining the original aspect ratio. Useful for maximizing vertical space usage when the terminal is resized.

Calculation:

Uses full terminal height (from terminal size detection)
Calculates width to maintain aspect ratio
Updates opt_width and opt_height global variables

Usage: Call this function when terminal is resized or when you want to maximize vertical space usage while preserving aspect ratio.

Example: If terminal is 120×40 and original dimensions were 80×30:

Original aspect ratio: 80/30 = 2.67
New dimensions: 107×40 (maintains 2.67 aspect ratio, uses full height)

Note: Updates global variables opt_width and opt_height; Maintains aspect ratio of current dimensions; Uses terminal size detection to get full height; Useful for dynamic terminal resizing

Update dimensions for full height display.

Sets opt_height to terminal height when auto-detected. Used during initialization to maximize vertical space usage.

Behavior:

Both auto: Set both width and height to terminal size
Only height auto: Set height to terminal height
Only width auto: Set width to terminal width
Neither auto: No change

Note: Does not use log_debug because logging may not be initialized yet; Fails silently if terminal size detection fails (keeps defaults)

Example:

// During options_init():
if (auto_height || auto_width) {
    update_dimensions_for_full_height();
}

Definition at line 535 of file options/common.c.

                                                        {
  if (!opts) {
    return;
  }
 
  unsigned short int term_width, term_height;
 
  // Note: Logging is not available during options_init, so we can't use log_debug here
  asciichat_error_t result = get_terminal_size(&term_width, &term_height);
  if (result == ASCIICHAT_OK) {
    // If both dimensions are auto, set height to terminal height and let
    // aspect_ratio calculate width
    if (opts->auto_height && opts->auto_width) {
      opts->height = term_height;
      opts->width = term_width; // Also set width when both are auto
    }
    // If only height is auto, use full terminal height
    else if (opts->auto_height) {
      opts->height = term_height;
    }
    // If only width is auto, use full terminal width
    else if (opts->auto_width) {
      opts->width = term_width;
    }
  } else {
    // Terminal size detection failed, but we can still continue with defaults
  }
}

References ASCIICHAT_OK, options_state::auto_height, options_state::auto_width, get_terminal_size(), options_state::height, and options_state::width.

Referenced by options_init().

◆ update_dimensions_to_terminal_size()

void update_dimensions_to_terminal_size ( options_t * opts )

#include <options.h>

Update dimensions to match terminal size.

Sets opt_width and opt_height to exactly match the current terminal dimensions. This function queries the terminal for its size and updates the option variables accordingly.

Detection: Uses platform-specific terminal size detection:

POSIX: TIOCGWINSZ ioctl on stdout
Windows: Console API GetConsoleScreenBufferInfo
Fallback: Environment variables ($COLUMNS, $LINES)
Final fallback: Default dimensions (OPT_WIDTH_DEFAULT, OPT_HEIGHT_DEFAULT)

Usage: Call this function:

After terminal resize (POSIX: SIGWINCH signal handler)
When auto-detection is enabled and dimensions need refreshing
When you want to sync dimensions with current terminal size

Example: Terminal is 160×60:

opt_width is set to 160
opt_height is set to 60

Note: Updates global variables opt_width and opt_height; Uses platform-specific terminal size detection; Handles detection failures gracefully (uses fallbacks); Useful for terminal resize handling

Update dimensions to match terminal size.

Updates opt_width and opt_height to current terminal size for auto-detected dimensions. Used after logging is initialized (can use log_debug).

Behavior:

auto_width: Set width to terminal width
auto_height: Set height to terminal height
Neither: No change

Note: Logs debug messages about dimension updates; Logs debug message if terminal size detection fails

Example:

// After logging initialization:
update_dimensions_to_terminal_size();
log_info("Terminal dimensions: %dx%d", opt_width, opt_height);

Definition at line 564 of file options/common.c.

                                                         {
  if (!opts) {
    return;
  }
 
  unsigned short int term_width, term_height;
  // Get current terminal size (get_terminal_size already handles ioctl first, then $COLUMNS/$LINES fallback)
  asciichat_error_t terminal_result = get_terminal_size(&term_width, &term_height);
  if (terminal_result == ASCIICHAT_OK) {
    if (opts->auto_width) {
      opts->width = term_width;
    }
    if (opts->auto_height) {
      opts->height = term_height;
    }
    log_debug("After update_dimensions_to_terminal_size: width=%d, height=%d", opts->width, opts->height);
  } else {
    // Terminal detection failed - keep the default values set in options_init()
    log_debug(
        "Failed to get terminal size in update_dimensions_to_terminal_size, keeping defaults: width=%d, height=%d",
        opts->width, opts->height);
  }
}

References ASCIICHAT_OK, options_state::auto_height, options_state::auto_width, get_terminal_size(), options_state::height, log_debug, and options_state::width.

Referenced by options_init().

◆ usage()

void usage	(	FILE *	desc,
		asciichat_mode_t	mode
	)

#include <options.h>

Print usage information for client, server, or mirror mode.

Parameters

desc	File descriptor to write to (typically stdout or stderr)
mode	Mode to show usage for (MODE_SERVER, MODE_CLIENT, or MODE_MIRROR)

Prints comprehensive usage information including:

Program description and synopsis
All available command-line options
Option descriptions and default values
Usage examples
Mode-specific options (client vs server)

Usage: Called automatically by options_init() for --help, or manually by application code when ERROR_USAGE is returned.

Output: Formatted usage text including:

Program name and version
Synopsis with command syntax
Option list with short/long forms and descriptions
Examples of common usage patterns

Example:: if (options_init(argc, argv, true) == ERROR_USAGE) {

usage(stderr, true); // Print client usage

return 1;

}

Note: Typically printed to stderr for error cases, stdout for --help; Output is mode-specific (different options for client vs server); Includes all available options with descriptions

Definition at line 592 of file options/common.c.

                                              {
  switch (mode) {
  case MODE_SERVER:
    usage_server(desc);
    break;
  case MODE_CLIENT:
    usage_client(desc);
    break;
  case MODE_MIRROR:
    usage_mirror(desc);
    break;
  case MODE_ACDS:
    usage_acds(desc);
    break;
  default:
    (void)fprintf(desc, "Unknown mode\n");
    break;
  }
}

References MODE_ACDS, MODE_CLIENT, MODE_MIRROR, MODE_SERVER, usage_acds(), usage_client(), usage_mirror(), and usage_server().

Referenced by main().

◆ usage_acds()

void usage_acds ( FILE * desc )

#include <options.h>

Print ACDS usage information.

Parameters

desc	File descriptor to write to (typically stdout or stderr)

Prints ACDS (ASCII Chat Discovery Service) specific usage information.

Usage: Called when displaying ACDS help or error messages.

Includes: All ACDS-specific options:

Network binding options (address, port)
Database configuration
Identity key management
STUN/TURN server configuration

Definition at line 109 of file acds.c.

                            {
  // Get config with program name and description
  const options_config_t *config = options_preset_acds("acds", "ascii-chat discovery service");
  if (!config) {
    (void)fprintf(desc, "Error: Failed to create options config\n");
    return;
  }
 
  (void)fprintf(desc, "%s - %s\n\n", config->program_name, config->description);
  (void)fprintf(desc, "USAGE:\n");
  (void)fprintf(desc, "  %s [options...]\n\n", config->program_name);
 
  // Print positional argument examples programmatically if they exist
  if (config->num_positional_args > 0) {
    const positional_arg_descriptor_t *pos_arg = &config->positional_args[0];
    if (pos_arg->section_heading && pos_arg->examples && pos_arg->num_examples > 0) {
      (void)fprintf(desc, "%s:\n", pos_arg->section_heading);
      for (size_t i = 0; i < pos_arg->num_examples; i++) {
        (void)fprintf(desc, "  %s\n", pos_arg->examples[i]);
      }
      (void)fprintf(desc, "\n");
    }
  }
 
  // Generate options from builder configuration
  options_config_print_usage(config, desc);
 
  // Clean up the config
  options_config_destroy(config);
}

References options_config_t::description, positional_arg_descriptor_t::examples, positional_arg_descriptor_t::num_examples, options_config_t::num_positional_args, options_config_destroy(), options_config_print_usage(), options_preset_acds(), options_config_t::positional_args, options_config_t::program_name, and positional_arg_descriptor_t::section_heading.

Referenced by usage().

◆ usage_client()

void usage_client ( FILE * desc )

#include <options.h>

Print client usage information.

Parameters

desc	File descriptor to write to (typically stdout or stderr)

Convenience function that prints client-specific usage information. Equivalent to usage(desc, true).

Usage: Called when displaying client help or error messages.

Includes: All client-specific options:

Display options (color mode, render mode, UTF-8)
Webcam options (device index, flip, test pattern)
Snapshot mode options
Terminal dimension options
Client-specific encryption options (server key verification)

Print client usage information.

Displays comprehensive help for all client options, including:

Description of client mode
Positional argument format and examples
All client-specific flags with descriptions
Shared flags (palette, encryption, output)
Usage examples for common scenarios

Output Format:

Client mode: Connect to ascii-chat server and display video grid
 
Usage: ascii-chat client [OPTIONS] [address][:port]
 
Positional Arguments:
  [address][:port]        Server address with optional port (default: localhost:27224)
                          Examples: localhost, 192.168.1.100:8080, [::1]:27224
 
Network Options:
  -p, --port PORT         Server port (default: 27224)
                          Note: Conflicts with port in positional argument
 
Webcam Options:
  -c, --webcam-index N    Webcam device index (default: 0)
  -f, --webcam-flip       Mirror webcam horizontally (default: true)
  --test-pattern          Use test pattern instead of real webcam
  --list-webcams          List available webcams and exit
 
[... continues with all option categories ...]

Parameters

stream Output stream (stdout for –help, stderr for errors)

Note: Does not exit - caller decides whether to exit after printing; Always includes mode description, positional args, and all flags; Examples show real-world usage patterns

Example usage:

// Print help and exit successfully
if (help_requested) {
    usage_client(stdout);
    exit(0);
}
 
// Print usage hint on error
if (parse_error) {
    fprintf(stderr, "Error: Invalid option\n\n");
    usage_client(stderr);
    exit(1);
}

See also: usage_server(); usage_mirror()

Definition at line 86 of file lib/options/client.c.

                              {
  // Get config with program name and description
  const options_config_t *config = options_preset_client("ascii-chat client", "connect to an ascii-chat server");
  if (!config) {
    (void)fprintf(desc, "Error: Failed to create options config\n");
    return;
  }
 
  // Print custom address format help first
  (void)fprintf(desc, "%s - %s\n\n", config->program_name, config->description);
  (void)fprintf(desc, "USAGE:\n");
  (void)fprintf(desc, "  %s [address][:port] [options...]\n\n", config->program_name);
 
  // Print positional argument examples programmatically
  if (config->num_positional_args > 0) {
    const positional_arg_descriptor_t *pos_arg = &config->positional_args[0];
    if (pos_arg->section_heading && pos_arg->examples && pos_arg->num_examples > 0) {
      (void)fprintf(desc, "%s:\n", pos_arg->section_heading);
      for (size_t i = 0; i < pos_arg->num_examples; i++) {
        (void)fprintf(desc, "  %s\n", pos_arg->examples[i]);
      }
      (void)fprintf(desc, "\n");
    }
  }
 
  // Generate options from builder configuration
  options_config_print_usage(config, desc);
 
  // Clean up the config
  options_config_destroy(config);
}

References options_config_t::description, positional_arg_descriptor_t::examples, positional_arg_descriptor_t::num_examples, options_config_t::num_positional_args, options_config_destroy(), options_config_print_usage(), options_preset_client(), options_config_t::positional_args, options_config_t::program_name, and positional_arg_descriptor_t::section_heading.

Referenced by action_help_client(), and usage().

◆ usage_mirror()

void usage_mirror ( FILE * desc )

#include <options.h>

Print mirror usage information.

Parameters

desc	File descriptor to write to (typically stdout or stderr)

Prints mirror mode (local webcam preview) usage information.

Usage: Called when displaying mirror help or error messages.

Includes: Mirror-specific options:

Display options (color mode, palette)
Webcam options
Terminal dimension options

Print mirror usage information.

Displays comprehensive help for all mirror options, including:

Description of mirror mode and use cases
All mirror-specific flags with descriptions
Palette and output options
Debug options
Usage examples for common scenarios
Notes on differences from client mode

Output Format:

Mirror mode: Display local webcam as ASCII art (no network connection)
 
Usage: ascii-chat mirror [OPTIONS]
 
Display Options:
  -x, --width WIDTH       Terminal width in characters (default: auto-detect)
  -y, --height HEIGHT     Terminal height in characters (default: auto-detect)
  --fps FPS               Target framerate (1-144, default: 30)
  --color-mode MODE       Color mode: auto, mono, 16, 256, truecolor (default: auto)
  --render-mode MODE      Render mode: foreground, background (default: foreground)
 
Webcam Options:
  -c, --webcam-index N    Webcam device index (default: 0)
  -f, --webcam-flip       Mirror webcam horizontally (default: true)
  --test-pattern          Use test pattern instead of real webcam
  --list-webcams          List available webcams and exit
 
Output Options:
  -s, --stretch           Stretch/shrink without preserving aspect ratio
  -q, --quiet             Disable console logging (log to file only)
  -S, --snapshot          Capture one frame and exit
  --snapshot-delay SEC    Delay before snapshot (default: 3.0 seconds)
  --strip-ansi            Strip ANSI escape sequences from output
 
Palette Options:
  -P, --palette TYPE      Palette type: standard, blocks, digital, minimal, cool, custom
  -C, --palette-chars S   Custom palette characters (dark to bright)
 
Debug Options:
  --show-capabilities     Show terminal capabilities and exit
  --utf8                  Force UTF-8 output (enables multi-byte characters)
 
[... continues with examples ...]

Parameters

stream Output stream (stdout for –help, stderr for errors)

Note: Does not exit - caller decides whether to exit after printing; Explicitly mentions that network/audio/crypto options are not available; Examples show standalone local usage patterns

Example usage:

// Print help and exit successfully
if (help_requested) {
    usage_mirror(stdout);
    exit(0);
}
 
// Print usage hint on error
if (parse_error) {
    fprintf(stderr, "Error: Invalid option\n\n");
    usage_mirror(stderr);
    exit(1);
}

See also: usage_client(); usage_server()

Definition at line 71 of file mirror.c.

                              {
  // Get config with program name and description
  const options_config_t *config = options_preset_mirror("ascii-chat mirror", "view local webcam as ascii art");
  if (!config) {
    (void)fprintf(desc, "Error: Failed to create options config\n");
    return;
  }
 
  (void)fprintf(desc, "%s - %s\n\n", config->program_name, config->description);
  (void)fprintf(desc, "USAGE:\n");
  (void)fprintf(desc, "  %s [options...]\n\n", config->program_name);
 
  // Generate options from builder configuration
  options_config_print_usage(config, desc);
 
  // Clean up the config
  options_config_destroy(config);
}

References options_config_t::description, options_config_destroy(), options_config_print_usage(), options_preset_mirror(), and options_config_t::program_name.

Referenced by action_help_mirror(), and usage().

◆ usage_server()

void usage_server ( FILE * desc )

#include <options.h>

Print server usage information.

Parameters

desc	File descriptor to write to (typically stdout or stderr)

Convenience function that prints server-specific usage information. Equivalent to usage(desc, false).

Usage: Called when displaying server help or error messages.

Includes: All server-specific options:

Network binding options (address, port, IPv6)
Server-specific encryption options (client keys whitelist)
Server configuration options

Definition at line 80 of file lib/options/server.c.

                              {
  // Get config with program name and description
  const options_config_t *config =
      options_preset_server("ascii-chat server", "host a server mixing video and audio for ascii-chat clients");
  if (!config) {
    (void)fprintf(desc, "Error: Failed to create options config\n");
    return;
  }
 
  // Print custom bind address help first
  (void)fprintf(desc, "%s - %s\n\n", config->program_name, config->description);
  (void)fprintf(desc, "USAGE:\n");
  (void)fprintf(desc, "  %s [bind-address] [bind-address6] [options...]\n\n", config->program_name);
 
  // Print positional argument examples programmatically
  if (config->num_positional_args > 0) {
    const positional_arg_descriptor_t *pos_arg = &config->positional_args[0];
    if (pos_arg->section_heading && pos_arg->examples && pos_arg->num_examples > 0) {
      (void)fprintf(desc, "%s:\n", pos_arg->section_heading);
      for (size_t i = 0; i < pos_arg->num_examples; i++) {
        (void)fprintf(desc, "  %s\n", pos_arg->examples[i]);
      }
      (void)fprintf(desc, "\n");
    }
  }
 
  // Generate options from builder configuration
  options_config_print_usage(config, desc);
 
  // Clean up the config
  options_config_destroy(config);
}

References options_config_t::description, positional_arg_descriptor_t::examples, positional_arg_descriptor_t::num_examples, options_config_t::num_positional_args, options_config_destroy(), options_config_print_usage(), options_preset_server(), options_config_t::positional_args, options_config_t::program_name, and positional_arg_descriptor_t::section_heading.

Referenced by action_help_server(), and usage().

◆ validate_opt_color_mode()

ASCIICHAT_API int validate_opt_color_mode	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate color mode string.

Parameters

value_str	Color mode value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed color mode enum value on success, -1 on error

Valid values: auto, none, mono, 16, 16color, 256, 256color, truecolor, 24bit

Validate color mode string Returns parsed color mode on success, -1 on error

Definition at line 94 of file validation.c.

                                                                                           {
  if (!value_str) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Color mode value is required");
    }
    return -1;
  }
 
  if (strcmp(value_str, "auto") == 0) {
    return COLOR_MODE_AUTO;
  }
  if (strcmp(value_str, "none") == 0 || strcmp(value_str, "mono") == 0) {
    return COLOR_MODE_NONE;
  }
  if (strcmp(value_str, "16") == 0 || strcmp(value_str, "16color") == 0) {
    return COLOR_MODE_16_COLOR;
  }
  if (strcmp(value_str, "256") == 0 || strcmp(value_str, "256color") == 0) {
    return COLOR_MODE_256_COLOR;
  }
  if (strcmp(value_str, "truecolor") == 0 || strcmp(value_str, "24bit") == 0) {
    return COLOR_MODE_TRUECOLOR;
  }
  if (error_msg) {
    SAFE_SNPRINTF(error_msg, error_msg_size,
                  "Invalid color mode '%s'. Valid modes: auto, none, mono, 16, 256, truecolor", value_str);
  }
  return -1;
}

References COLOR_MODE_16_COLOR, COLOR_MODE_256_COLOR, COLOR_MODE_AUTO, COLOR_MODE_NONE, COLOR_MODE_TRUECOLOR, and SAFE_SNPRINTF.

◆ validate_opt_compression_level()

ASCIICHAT_API int validate_opt_compression_level	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate compression level (1-9)

Parameters

value_str	Compression level as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed level on success, -1 on error

Validates zstd compression level in range 1-9.

Validate compression level (1-9) Returns parsed value on success, -1 on error

Definition at line 327 of file validation.c.

                                                                                                  {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Compression level value is required");
    }
    return -1;
  }
 
  int level = strtoint_safe(value_str);
  if (level == INT_MIN || level < 1 || level > 9) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid compression level '%s'. Must be between 1 and 9.", value_str);
    }
    return -1;
  }
  return level;
}

References SAFE_SNPRINTF, and strtoint_safe().

◆ validate_opt_device_index()

ASCIICHAT_API int validate_opt_device_index	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate device index (-1 for default, 0+ for specific device)

Parameters

value_str	Device index as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed index on success, INT_MIN on error

Used for microphone-index, speakers-index, webcam-index. -1 means use system default device.

Validate device index (-1 for default, or 0+ for specific device) Returns parsed value on success, INT_MIN on error

Definition at line 422 of file validation.c.

                                                                                             {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Device index value is required");
    }
    return INT_MIN;
  }
 
  int index = strtoint_safe(value_str);
  if (index == INT_MIN) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size,
                    "Invalid device index '%s'. Must be -1 (default) or a non-negative integer.", value_str);
    }
    return INT_MIN;
  }
 
  // -1 is valid (system default), otherwise must be >= 0
  if (index < -1) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size,
                    "Invalid device index '%d'. Must be -1 (default) or a non-negative integer.", index);
    }
    return INT_MIN;
  }
  return index;
}

References SAFE_SNPRINTF, and strtoint_safe().

Referenced by validate_webcam_index().

◆ validate_opt_float_non_negative()

ASCIICHAT_API float validate_opt_float_non_negative	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate non-negative float value.

Parameters

value_str	Float value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed float value on success, -1.0f on error

Validates that the string is a valid non-negative floating-point number.

Validate float value (non-negative) Returns parsed value on success, returns -1.0f on error (caller must check)

Definition at line 276 of file validation.c.

                                                                                                     {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Value is required");
    }
    return -1.0f;
  }
 
  char *endptr;
  float val = strtof(value_str, &endptr);
  if (*endptr != '\0' || value_str == endptr) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid float value '%s'. Must be a number.", value_str);
    }
    return -1.0f;
  }
  if (val < 0.0f) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Value must be non-negative (got %.2f)", val);
    }
    return -1.0f;
  }
  return val;
}

References SAFE_SNPRINTF.

◆ validate_opt_fps()

ASCIICHAT_API int validate_opt_fps	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate FPS value (1-144)

Parameters

value_str	FPS value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed FPS value on success, -1 on error

Validates that the FPS is in the valid range of 1-144.

Validate FPS value (1-144) Returns parsed value on success, -1 on error

Definition at line 349 of file validation.c.

                                                                                    {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "FPS value is required");
    }
    return -1;
  }
 
  int fps_val = strtoint_safe(value_str);
  if (fps_val == INT_MIN || fps_val < 1 || fps_val > 144) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid FPS value '%s'. FPS must be between 1 and 144.", value_str);
    }
    return -1;
  }
  return fps_val;
}

References SAFE_SNPRINTF, and strtoint_safe().

◆ validate_opt_ip_address()

ASCIICHAT_API int validate_opt_ip_address	(	const char *	value_str,
		char *	parsed_address,
		size_t	address_size,
		bool	is_client,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate IP address or hostname.

Parameters

value_str	IP address or hostname as string
parsed_address	Buffer to store resolved/parsed address
address_size	Size of parsed_address buffer
is_client	True if client mode (for error messages)
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: 0 on success, -1 on error

Validates IPv4, IPv6 addresses, or resolves hostname to IP.

Validate IP address or hostname Returns 0 on success, -1 on error Sets parsed_address on success (resolved if hostname)

Definition at line 224 of file validation.c.

                                                                    {
  (void)is_client; // Parameter not used but kept for API consistency
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Address value is required");
    }
    return -1;
  }
 
  // Parse IPv6 address (remove brackets if present)
  char parsed_addr[OPTIONS_BUFF_SIZE];
  if (parse_ipv6_address(value_str, parsed_addr, sizeof(parsed_addr)) == 0) {
    value_str = parsed_addr;
  }
 
  // Check if it's a valid IPv4 address
  if (is_valid_ipv4(value_str)) {
    SAFE_SNPRINTF(parsed_address, address_size, "%s", value_str);
    return 0;
  }
  // Check if it's a valid IPv6 address
  if (is_valid_ipv6(value_str)) {
    SAFE_SNPRINTF(parsed_address, address_size, "%s", value_str);
    return 0;
  }
  // Check if it looks like an invalid IP (has dots but not valid IPv4 format)
  if (strchr(value_str, '.') != NULL) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size,
                    "Invalid IP address format '%s'. IPv4 addresses must have exactly 4 octets.", value_str);
    }
    return -1;
  }
 
  // Otherwise, try to resolve as hostname
  char resolved_ip[OPTIONS_BUFF_SIZE];
  if (platform_resolve_hostname_to_ipv4(value_str, resolved_ip, sizeof(resolved_ip)) == 0) {
    SAFE_SNPRINTF(parsed_address, address_size, "%s", resolved_ip);
    return 0;
  } else {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Failed to resolve hostname '%s' to IP address.", value_str);
    }
    return -1;
  }
}

References is_valid_ipv4(), is_valid_ipv6(), OPTIONS_BUFF_SIZE, parse_ipv6_address(), platform_resolve_hostname_to_ipv4(), and SAFE_SNPRINTF.

◆ validate_opt_log_level()

ASCIICHAT_API int validate_opt_log_level	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate log level string.

Parameters

value_str	Log level as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed log level enum value on success, -1 on error

Valid values (case-insensitive): dev, debug, info, warn, error, fatal

Validate log level string Returns parsed log level on success, -1 on error

Definition at line 190 of file validation.c.

                                                                                          {
  if (!value_str) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Log level value is required");
    }
    return -1;
  }
 
  if (platform_strcasecmp(value_str, "dev") == 0) {
    return LOG_DEV;
  } else if (platform_strcasecmp(value_str, "debug") == 0) {
    return LOG_DEBUG;
  } else if (platform_strcasecmp(value_str, "info") == 0) {
    return LOG_INFO;
  } else if (platform_strcasecmp(value_str, "warn") == 0) {
    return LOG_WARN;
  } else if (platform_strcasecmp(value_str, "error") == 0) {
    return LOG_ERROR;
  } else if (platform_strcasecmp(value_str, "fatal") == 0) {
    return LOG_FATAL;
  } else {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size,
                    "Invalid log level '%s'. Valid levels: dev, debug, info, warn, error, fatal", value_str);
    }
    return -1;
  }
}

References LOG_DEBUG, LOG_DEV, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_WARN, platform_strcasecmp(), and SAFE_SNPRINTF.

Referenced by parse_log_level_option().

◆ validate_opt_max_clients()

ASCIICHAT_API int validate_opt_max_clients	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate max clients value (1-32)

Parameters

value_str	Max clients value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed value on success, -1 on error

Validates that the max clients is in the valid range of 1-32.

Validate max clients (1-32) Returns parsed value on success, -1 on error

Definition at line 305 of file validation.c.

                                                                                            {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Max clients value is required");
    }
    return -1;
  }
 
  int max = strtoint_safe(value_str);
  if (max == INT_MIN || max < 1 || max > 32) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid max clients '%s'. Must be between 1 and 32.", value_str);
    }
    return -1;
  }
  return max;
}

References SAFE_SNPRINTF, and strtoint_safe().

◆ validate_opt_non_negative_int()

ASCIICHAT_API int validate_opt_non_negative_int	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate non-negative integer.

Parameters

value_str	Integer value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed value on success, -1 on error

Validates that the string is a non-negative integer (>= 0).

Validate non-negative integer Returns parsed value on success, -1 on error

Definition at line 72 of file validation.c.

                                                                                                 {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Value is required");
    }
    return -1;
  }
 
  int val = strtoint_safe(value_str);
  if (val == INT_MIN || val < 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid value '%s'. Must be a non-negative integer.", value_str);
    }
    return -1;
  }
  return val;
}

References SAFE_SNPRINTF, and strtoint_safe().

◆ validate_opt_palette()

ASCIICHAT_API int validate_opt_palette	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate palette type string.

Parameters

value_str	Palette type as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed palette type enum value on success, -1 on error

Valid values: standard, blocks, digital, minimal, cool, custom

Validate palette type string Returns parsed palette type on success, -1 on error

Definition at line 156 of file validation.c.

                                                                                        {
  if (!value_str) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Palette value is required");
    }
    return -1;
  }
 
  if (strcmp(value_str, "standard") == 0) {
    return PALETTE_STANDARD;
  } else if (strcmp(value_str, "blocks") == 0) {
    return PALETTE_BLOCKS;
  } else if (strcmp(value_str, "digital") == 0) {
    return PALETTE_DIGITAL;
  } else if (strcmp(value_str, "minimal") == 0) {
    return PALETTE_MINIMAL;
  } else if (strcmp(value_str, "cool") == 0) {
    return PALETTE_COOL;
  } else if (strcmp(value_str, "custom") == 0) {
    return PALETTE_CUSTOM;
  } else {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size,
                    "Invalid palette '%s'. Valid palettes: standard, blocks, digital, minimal, cool, custom",
                    value_str);
    }
    return -1;
  }
}

References PALETTE_BLOCKS, PALETTE_COOL, PALETTE_CUSTOM, PALETTE_DIGITAL, PALETTE_MINIMAL, PALETTE_STANDARD, and SAFE_SNPRINTF.

◆ validate_opt_password()

ASCIICHAT_API int validate_opt_password	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate password (8-256 characters)

Parameters

value_str	Password string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: 0 on success, -1 on error

Validates password length is 8-256 characters and contains no null bytes.

Validate password (8-256 characters, no null bytes) Returns 0 on success, -1 on error

Definition at line 454 of file validation.c.

                                                                                         {
  if (!value_str) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Password value is required");
    }
    return -1;
  }
 
  size_t len = strlen(value_str);
  if (len < 8) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Password too short (%zu chars). Must be at least 8 characters.", len);
    }
    return -1;
  }
  if (len > 256) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Password too long (%zu chars). Must be at most 256 characters.", len);
    }
    return -1;
  }
 
  // Note: No need to check for embedded null bytes - strlen() already stopped at the first null,
  // so by definition there are no null bytes within [0, len).
 
  return 0;
}

References SAFE_SNPRINTF.

◆ validate_opt_port()

ASCIICHAT_API int validate_opt_port	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate port number (1-65535)

Parameters

value_str	Port number as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: 0 on success, -1 on error

Validates that the port string is a valid number in the range 1-65535.

Validate port number (1-65535) Returns 0 on success, non-zero on error

Definition at line 26 of file validation.c.

                                                                                     {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Port value is required");
    }
    return -1;
  }
 
  // Use safe integer parsing with range validation
  uint16_t port_num;
  if (parse_port(value_str, &port_num) != ASCIICHAT_OK) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid port value '%s'. Port must be a number between 1 and 65535.",
                    value_str);
    }
    return -1;
  }
  return 0;
}

References ASCIICHAT_OK, parse_port(), and SAFE_SNPRINTF.

◆ validate_opt_positive_int()

ASCIICHAT_API int validate_opt_positive_int	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate positive integer.

Parameters

value_str	Integer value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed value on success, -1 on error

Validates that the string is a positive integer (> 0).

Validate positive integer Returns parsed value on success, -1 on error

Definition at line 50 of file validation.c.

                                                                                             {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Value is required");
    }
    return -1;
  }
 
  int val = strtoint_safe(value_str);
  if (val == INT_MIN || val <= 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid value '%s'. Must be a positive integer.", value_str);
    }
    return -1;
  }
  return val;
}

References SAFE_SNPRINTF, and strtoint_safe().

◆ validate_opt_reconnect()

ASCIICHAT_API int validate_opt_reconnect	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate reconnect value.

Parameters

value_str	Reconnect value as string ("off", "auto", or 0-999)
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: 0 for off, -1 for auto, 1-999 for count, INT_MIN on error

Valid values:

"off" or "0": No reconnection (returns 0)
"auto" or "-1": Unlimited reconnection (returns -1)
"1" to "999": Retry count (returns the count)

Validate reconnect value (off, auto, 0, -1, or 1-999) Returns: 0 for "off" (no retries) -1 for "auto" (unlimited retries) 1-999 for specific retry count INT_MIN on parse error

Definition at line 375 of file validation.c.

                                                                                          {
  if (!value_str || strlen(value_str) == 0) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Reconnect value is required");
    }
    return INT_MIN;
  }
 
  // Check for string values first
  if (platform_strcasecmp(value_str, "off") == 0) {
    return 0; // No retries
  }
  if (platform_strcasecmp(value_str, "auto") == 0) {
    return -1; // Unlimited retries
  }
 
  // Parse as integer
  int val = strtoint_safe(value_str);
  if (val == INT_MIN) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid reconnect value '%s'. Use 'off', 'auto', or a number 0-999.",
                    value_str);
    }
    return INT_MIN;
  }
 
  // 0 means off, -1 means auto, 1-999 is valid range
  if (val == 0) {
    return 0; // No retries
  }
  if (val == -1) {
    return -1; // Unlimited retries
  }
  if (val < 1 || val > 999) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Invalid reconnect count '%s'. Must be 'off', 'auto', or 1-999.",
                    value_str);
    }
    return INT_MIN;
  }
  return val;
}

References platform_strcasecmp(), SAFE_SNPRINTF, and strtoint_safe().

◆ validate_opt_render_mode()

ASCIICHAT_API int validate_opt_render_mode	(	const char *	value_str,
		char *	error_msg,
		size_t	error_msg_size
	)

#include <validation.h>

Validate render mode string.

Parameters

value_str	Render mode value as string
error_msg	Buffer for error message (can be NULL)
error_msg_size	Size of error message buffer

Returns: Parsed render mode enum value on success, -1 on error

Valid values: foreground, fg, background, bg, half-block, halfblock

Validate render mode string Returns parsed render mode on success, -1 on error

Definition at line 128 of file validation.c.

                                                                                            {
  if (!value_str) {
    if (error_msg) {
      SAFE_SNPRINTF(error_msg, error_msg_size, "Render mode value is required");
    }
    return -1;
  }
 
  if (strcmp(value_str, "foreground") == 0 || strcmp(value_str, "fg") == 0) {
    return RENDER_MODE_FOREGROUND;
  }
  if (strcmp(value_str, "background") == 0 || strcmp(value_str, "bg") == 0) {
    return RENDER_MODE_BACKGROUND;
  }
  if (strcmp(value_str, "half-block") == 0 || strcmp(value_str, "halfblock") == 0) {
    return RENDER_MODE_HALF_BLOCK;
  }
  if (error_msg) {
    SAFE_SNPRINTF(error_msg, error_msg_size,
                  "Invalid render mode '%s'. Valid modes: foreground, background, half-block", value_str);
  }
  return -1;
}

References RENDER_MODE_BACKGROUND, RENDER_MODE_FOREGROUND, RENDER_MODE_HALF_BLOCK, and SAFE_SNPRINTF.

Variable Documentation

◆ BLUE

unsigned short int BLUE[]

extern

#include <options.h>

Blue channel lookup table.

Lookup table for blue channel values. See RED[] for details.

Definition at line 354 of file options/common.c.

Referenced by precalc_rgb_palettes().

◆ GRAY

unsigned short int GRAY[]

extern

#include <options.h>

Grayscale lookup table.

Lookup table for grayscale values. Used for monochrome ASCII conversion when color information is not needed or available.

Definition at line 355 of file options/common.c.

Referenced by precalc_rgb_palettes().

◆ GREEN

unsigned short int GREEN[]

extern

#include <options.h>

Green channel lookup table.

Lookup table for green channel values. See RED[] for details.

Definition at line 353 of file options/common.c.

Referenced by precalc_rgb_palettes().

◆ opt_acds_database_path

ASCIICHAT_API char opt_acds_database_path[OPTIONS_BUFF_SIZE]

extern

#include <acds.h>

SQLite database path (ACDS mode only)

Path to SQLite database for session storage and management.

Default: ~/.config/ascii-chat/acds.db

Command-line: --database <path> or -d <path>

Note: ACDS mode only

Definition at line 41 of file acds.c.

Referenced by main(), and parse_acds_options().

◆ opt_acds_key_path

ASCIICHAT_API char opt_acds_key_path[OPTIONS_BUFF_SIZE]

extern

#include <acds.h>

Ed25519 identity key path (ACDS mode only)

Path to Ed25519 identity key for server identity.

Default: ~/.config/ascii-chat/acds_identity

Command-line: --key <path> or -k <path>

Note: ACDS mode only

Definition at line 42 of file acds.c.

Referenced by main(), and parse_acds_options().

◆ opt_acds_port

ASCIICHAT_API int opt_acds_port

extern

#include <acds.h>

TCP listen port (ACDS mode only)

Port number for the discovery service to listen on.

Default: 27225 (ACDS default port)

Command-line: --port <port> or -p <port>

Note: ACDS mode only

Definition at line 40 of file acds.c.

Referenced by main().

◆ RED

unsigned short int RED[]

extern

#include <options.h>

Red channel lookup table.

Lookup table for red channel values. Used for efficient color-to-ASCII character mapping. Precomputed table for fast palette lookups.

Usage: These lookup tables are used internally by the ASCII conversion algorithm for efficient color mapping.

Note: These are internal implementation details; Tables are precomputed based on palette and color mode; Access these tables via palette functions, not directly

Definition at line 352 of file options/common.c.

Referenced by precalc_rgb_palettes().

◆ weight_blue

const float weight_blue

extern

#include <options.h>

Blue weight for luminance calculation.

Weight for blue channel in luminance calculation. See weight_red for details.

Default: Typically 0.114 (standard ITU-R BT.601 weights)

Definition at line 348 of file options/common.c.

Referenced by server_main().

◆ weight_green

const float weight_green

extern

#include <options.h>

Green weight for luminance calculation.

Weight for green channel in luminance calculation. See weight_red for details.

Default: Typically 0.587 (standard ITU-R BT.601 weights)

Definition at line 347 of file options/common.c.

Referenced by server_main().

◆ weight_red

const float weight_red

extern

#include <options.h>

Definition at line 346 of file options/common.c.

Referenced by server_main().

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Utility Functions

Option Parsing Functions

Dimension Update Functions

Validation Functions

Configuration Constants

Detailed Description

Options README

Overview

Operation Modes

Common Options

Usage Examples

Server Examples

Client Examples

Programmatic API

Help System

Macro Definition Documentation

◆ ASCIICHAT_ACDS_OPTIONS_STRUCT

◆ ASCIICHAT_BINARY_OPTIONS_STRUCT

◆ ASCIICHAT_CLIENT_OPTIONS_STRUCT

◆ ASCIICHAT_COMMON_OPTIONS_STRUCT

◆ ASCIICHAT_MIRROR_OPTIONS_STRUCT

◆ ASCIICHAT_SERVER_OPTIONS_STRUCT

◆ COLOR_MODE_16

◆ COLOR_MODE_16_COLOR

◆ COLOR_MODE_256

◆ COLOR_MODE_256_COLOR

◆ COLOR_MODE_AUTO

◆ COLOR_MODE_NONE

◆ COLOR_MODE_TRUECOLOR

◆ GET_OPTION

◆ LEVENSHTEIN_SUGGESTION_THRESHOLD

◆ OPT_ADDRESS6_DEFAULT

◆ OPT_ADDRESS_DEFAULT

◆ OPT_COLOR_MODE_DEFAULT

◆ OPT_COMPRESSION_LEVEL_DEFAULT

◆ OPT_ENCODE_AUDIO_DEFAULT

◆ OPT_FPS_DEFAULT

◆ OPT_HEIGHT_DEFAULT

◆ OPT_MAX_CLIENTS_DEFAULT

◆ OPT_MICROPHONE_INDEX_DEFAULT

◆ OPT_PORT_DEFAULT

◆ OPT_RECONNECT_ATTEMPTS_DEFAULT

◆ OPT_RENDER_MODE_DEFAULT

◆ OPT_SPEAKERS_INDEX_DEFAULT

◆ OPT_WEBCAM_FLIP_DEFAULT

◆ OPT_WEBCAM_INDEX_DEFAULT

◆ OPT_WIDTH_DEFAULT

◆ OPTIONS_BUFF_SIZE

◆ SNAPSHOT_DELAY_DEFAULT

Typedef Documentation

◆ options_t

Enumeration Type Documentation

◆ asciichat_mode_t

Function Documentation

◆ levenshtein()

◆ levenshtein_find_similar()

◆ levenshtein_n()

◆ options_get()

◆ options_init()

◆ options_set_color_mode()

◆ options_set_dimensions()

◆ options_set_log_level()

◆ options_set_render_mode()

◆ options_update()

◆ strtoint_safe()

◆ update_dimensions_for_full_height()

◆ update_dimensions_to_terminal_size()

◆ usage()

◆ usage_acds()

◆ usage_client()

◆ usage_mirror()

◆ usage_server()

◆ validate_opt_color_mode()