The toml text file configuration file module. More...

Files
file	config.c
	📋 TOML configuration file parser with schema validation and CLI override support

file	config.h
	TOML configuration file support for ascii-chat.

Functions
asciichat_error_t	config_load_and_apply (bool is_client, const char config_path, bool strict, options_t opts)
	Main function to load configuration from file and apply to global options.

asciichat_error_t	config_create_default (const char config_path, const options_t opts)
	Create default configuration file with all default values.

asciichat_error_t	config_load_system_and_user (bool is_client, const char user_config_path, bool strict, options_t opts)
	Load system config first, then user config (user config overrides system)

Detailed Description

The toml text file configuration file module.

This module provides functionality for loading configuration from TOML files (typically located at ~/.ascii-chat/config.toml). Configuration values are applied to global options, but command-line arguments always take precedence over config file values.

The interface provides:

TOML file parsing and validation
Automatic configuration loading from standard location
Non-fatal error handling (missing or malformed config files are ignored)
Support for network, client, palette, crypto, and logging configuration

Note

Configuration Priority: Command-line arguments override config file values. Config file values override default values. The config file is loaded before CLI argument parsing to ensure this precedence.

Configuration File Location: The config file is loaded from the ascii-chat configuration directory:

Unix: $XDG_CONFIG_HOME/ascii-chat/config.toml if set, otherwise ~/.ascii-chat/config.toml
Windows: APPDATA%\ascii-chat\config.toml if set, otherwise ~\.ascii-chat\config.toml

Error Handling: Config file parsing errors are non-fatal. If the file is missing, malformed, or contains invalid values, warnings are printed to stderr and the application continues with default values. Invalid individual values are skipped with warnings, but valid values are still applied.

Validation: All configuration values are validated using the same validation functions used by CLI argument parsing, ensuring consistency between config file and CLI option handling.

Warning: Password Storage: While passwords can be stored in the config file (via crypto.password), this is strongly discouraged for security reasons. A warning is printed if a password is found in the config file. Use CLI --password or environment variables instead.; File Permissions: Users should secure their config file to prevent unauthorized access, especially if it contains sensitive information like encryption keys or passwords.

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

Date: October 2025

Configuration README

Command-line argument parsing and TOML-based configuration file management for flexible server and client setup.

Overview

ascii-chat supports two configuration methods:

Command-line arguments: Quick configuration for ad-hoc usage
TOML configuration files: Persistent, structured configuration

Command-line arguments override configuration file settings, allowing:

Default configuration in ~/.config/ascii-chat/config.toml
Per-session overrides via command-line flags
Easy scripting and automation

TOML Configuration Files

ascii-chat uses TOML (Tom's Obvious, Minimal Language) for configuration files, parsed by the tomlc17 library.

File Format

Complete example configuration:

# ascii-chat Configuration File
# Location: ~/.config/ascii-chat/config.toml
 
[server]
# Bind address ("::" for all IPv6/IPv4, "0.0.0.0" for IPv4 only)
address = "::"
 
# Server port (default: 27224)
port = 27224
 
# Maximum simultaneous clients (1-9)
max_clients = 9
 
# Server identity key (SSH Ed25519 format)
key_file = "~/.ssh/ascii-chat-server"
 
# Authorized client public keys (SSH format or github:username)
# Leave empty to allow all clients (less secure)
client_keys = [
    "github:alice",
    "github:bob",
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... charlie@example.com"
]
 
[client]
# Server address to connect to
address = "localhost"
 
# Server port
port = 27224
 
# Expected server public key (for TOFU verification)
# Leave empty to accept any server (prompts for confirmation)
server_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
 
# Client identity key
key_file = "~/.ssh/id_ed25519"
 
# Connection timeout (seconds)
timeout = 10
 
[video]
# Terminal width (auto-detected if not specified)
width = 160
 
# Terminal height (auto-detected if not specified)
height = 45
 
# Enable color output (true/false)
color = true
 
# Use half-block characters for 2x vertical resolution
half_blocks = true
 
# ASCII palette (characters from dark to bright)
palette = " .:-=+*#%@"
 
# Webcam device index (0 = first camera)
webcam_device = 0
 
# Capture resolution (before scaling to terminal size)
capture_width = 1920
capture_height = 1080
 
# Target framerate
fps = 30
 
[audio]
# Enable audio capture/playback
enabled = true
 
# Sample rate (Hz)
sample_rate = 48000
 
# Audio channels (1=mono, 2=stereo)
channels = 1
 
# PortAudio buffer size (frames)
buffer_size = 512
 
# Audio input device (-1 = default)
input_device = -1
 
# Audio output device (-1 = default)
output_device = -1
 
[logging]
# Log file path (empty = stderr only)
file = "/tmp/ascii-chat.log"
 
# Log level (debug, info, warn, error, fatal)
level = "info"
 
# Enable color in log output
color = true

Loading Configuration

Load Config File:

#include "config.h"
#include "options.h"
 
options_t opts;
asciichat_error_t err = config_load(&opts, "~/.config/ascii-chat/config.toml");
if (err != ASCIICHAT_OK) {
    log_error("Failed to load config file");
    return err;
}
 
// Configuration is now available in opts structure
log_info("Server address: %s:%d", opts.address, opts.port);
log_info("Max clients: %d", opts.max_clients);
log_info("Video: %dx%d @ %d FPS", opts.width, opts.height, opts.fps);
 
// Cleanup
options_destroy(&opts);

Apply Defaults:

// Initialize with default values
options_t opts = {0};
apply_default_options(&opts);

Command-Line Options

Server Options

# Start server with defaults
./ascii-chat server
 
# Bind to specific address and port
./ascii-chat server :: --port 27224
 
# Bind to IPv4 only
./ascii-chat server 0.0.0.0 --port 27224
 
# Use server identity key
./ascii-chat server --key ~/.ssh/ascii-chat-server
 
# Authorize specific clients
./ascii-chat server --client-keys github:alice,github:bob
 
# Limit maximum clients
./ascii-chat server --max-clients 4
 
# Enable color and set log file
./ascii-chat server --color --log-file /tmp/server.log
 
# Use configuration file
./ascii-chat --config ~/.config/ascii-chat/server.toml server

Server-specific flags:

[address1] [address2] (positional): Bind addresses, 0-2 IPv4/IPv6 addresses (default: 127.0.0.1 and ::1)
--port, -p PORT: Listen port (default: 27224)
--key KEY_FILE: Server identity key (SSH Ed25519)
--client-keys KEYS: Comma-separated authorized client keys
--max-clients N: Maximum simultaneous clients (1-9, default: 9)

Client Options

# Connect to localhost (default)
./ascii-chat client
 
# Connect to specific server
./ascii-chat client example.com:27224
 
# Specify terminal dimensions
./ascii-chat client --width 160 --height 45
 
# Enable color and half-blocks
./ascii-chat client --color --half-blocks
 
# Use custom ASCII palette
./ascii-chat client --palette " .:-=+*#%@"
 
# Enable audio
./ascii-chat client --audio
 
# Verify server identity
./ascii-chat client --server-key ~/.ssh/server_key.pub
 
# Use client identity key
./ascii-chat client --key ~/.ssh/id_ed25519
 
# Snapshot mode (capture and exit)
./ascii-chat client --snapshot --snapshot-delay 10
 
# Use configuration file
./ascii-chat --config ~/.config/ascii-chat/client.toml client example.com

Client-specific flags:

[address][:port] (positional): Server address with optional port (default: localhost:27224)
--port, -p PORT: Server port (default: 27224) - conflicts with port in positional argument
--width, -w WIDTH: Terminal width (default: auto-detect)
--height, -h HEIGHT: Terminal height (default: auto-detect)
--color, -c: Enable color output
--half-blocks: Use half-block characters (2x vertical resolution)
--palette, -P PALETTE: ASCII palette type (standard, blocks, digital, minimal, cool, custom)
--palette-chars, -C CHARS: Custom palette characters string
--audio, -A: Enable audio capture/playback
--server-key KEY: Expected server public key (TOFU)
--key KEY_FILE: Client identity key
--snapshot: Snapshot mode (capture once and exit)
--snapshot-delay SECONDS: Snapshot duration before exit

Common Options

Available for both server and client:

--config FILE: Configuration file path
–log-file FILE: Log file path
–help, -?: Show help message
–version, -v: Show version information

Default Config Locations

All ascii-chat data files (config.toml, known_hosts) are stored in a single directory:

Linux/macOS:

$XDG_CONFIG_HOME/ascii-chat/ (if XDG_CONFIG_HOME is set)
~/.ascii-chat/ (default when XDG_CONFIG_HOME is not set)

Windows:

APPDATA%\ascii-chat\ (if APPDATA is set)
~\.ascii-chat\ (default when APPDATA is not set)

Creating a Default Config:

# Create config at default location
./ascii-chat --config-create
 
# Create config at custom location
./ascii-chat --config-create ~/.my-config.toml
 
# Overwrite existing config (scripted - supports piped input)
echo "y" | ./ascii-chat --config-create
yes | ./ascii-chat --config-create /tmp/server.toml

Using a Config File:

./ascii-chat --config ~/.ascii-chat/config.toml server

./ascii-chat --config ~/.ascii-chat/config.toml client example.com

Overriding Config with CLI:

# Config file sets port=27224, but override it with --port

./ascii-chat --config ~/.ascii-chat/config.toml client --port 8080

Configuration Precedence

Settings are applied in this order (later overrides earlier):

Built-in defaults - Hardcoded default values
Config file - Values from TOML configuration (if specified with –config)
Environment variables - LOG_LEVEL, etc.
Command-line arguments - Highest priority

Example:

# Config file has port=27224
# Environment has LOG_LEVEL=1
# Command line has --port 8080
# Result: port=8080 (CLI wins), log_level=1 (from env)

Configuration Validation

The configuration system automatically validates all settings:

Automatic Validation:

Port range validation (1-65535)
Webcam index validation
File path validation (key files, config files)
Log level validation (0-4)
IP address format validation
Dimensions validation (width: 20-500, height: 10-200)
Client limits (max_clients: 1-9, grid layout constraint)
Tilde expansion for home directory (~/)
SSH keys must be Ed25519 format
Palette strings (must have at least 2 characters, ordered dark → bright)
UTF-8 validation for multi-byte characters

Error Reporting:

asciichat_error_t err = config_load(&opts, "~/.ascii-chat/config.toml");
if (err != ASCIICHAT_OK) {
    asciichat_error_context_t ctx;
    if (HAS_ERRNO(&ctx)) {
        log_error("Invalid configuration: %s", ctx.context_message);
    }
    return err;
}

Example validation code:

asciichat_error_t validate_config(const options_t *opts) {
    if (opts->port < 1 || opts->port > 65535) {
        return SET_ERRNO(ERROR_CONFIG_INVALID,
                          "Port must be 1-65535 (got %d)", opts->port);
    }
 
    if (opts->max_clients < 1 || opts->max_clients > 9) {
        return SET_ERRNO(ERROR_CONFIG_INVALID,
                          "max_clients must be 1-9 (got %d)", opts->max_clients);
    }
 
    if (opts->palette && strlen(opts->palette) < 2) {
        return SET_ERRNO(ERROR_CONFIG_INVALID,
                          "Palette must have at least 2 characters");
    }
 
    return ASCIICHAT_OK;
}

Usage Examples

Parsing Command-Line and Config File

int main(int argc, char **argv) {
    options_t opts;
    asciichat_error_t err;
 
    // Parse command-line arguments
    err = options_parse(&opts, argc, argv);
    if (err != ASCIICHAT_OK) {
        fprintf(stderr, "Usage: %s [server|client] [OPTIONS]\n", argv[0]);
        return 1;
    }
 
    // Load configuration file if specified
    if (opts.config_file) {
        err = config_load(&opts, opts.config_file);
        if (err != ASCIICHAT_OK) {
            log_error("Failed to load config: %s", opts.config_file);
            options_destroy(&opts);
            return 1;
        }
    }
 
    // Validate configuration
    err = validate_config(&opts);
    if (err != ASCIICHAT_OK) {
        asciichat_error_context_t ctx;
        if (HAS_ERRNO(&ctx)) {
            log_error("Invalid configuration: %s", ctx.context_message);
        }
        options_destroy(&opts);
        return 1;
    }
 
    // Use configuration...
    if (opts.mode == MODE_SERVER) {
        run_server(&opts);
    } else {
        run_client(&opts);
    }
 
    // Cleanup
    options_destroy(&opts);
    return 0;
}

Setting Defaults

void options_set_defaults(options_t *opts) {
    memset(opts, 0, sizeof(*opts));
 
    // Network defaults
    opts->port = DEFAULT_PORT;  // 27224
    opts->address = strdup("::");  // Dual-stack IPv6/IPv4
 
    // Video defaults
    opts->width = DEFAULT_WIDTH;   // 80 (or auto-detect)
    opts->height = DEFAULT_HEIGHT; // 24 (or auto-detect)
    opts->fps = DEFAULT_FPS;       // 30
    opts->color = true;
    opts->half_blocks = false;
    opts->palette = strdup(" .:-=+*#%@");
 
    // Audio defaults
    opts->audio = false;  // Disabled by default for client
    opts->sample_rate = SAMPLE_RATE;  // 48000
    opts->audio_channels = AUDIO_CHANNELS;  // 1 (mono)
 
    // Logging defaults
    opts->log_level = LOG_INFO;
    opts->log_color = true;
}

See also: Options for command-line argument parsing; options.h; config.h

Function Documentation

◆ config_create_default()

asciichat_error_t config_create_default	(	const char *	config_path,
		const options_t *	opts
	)

#include <config.c>

Create default configuration file with all default values.

Parameters

config_path	Path to config file to create (NULL uses default location)
opts	Options structure with values to write (use defaults for a "default" config)

Returns: ASCIICHAT_OK on success, error code on failure

Creates a new configuration file at the specified path (or default location if config_path is NULL) with all configuration options set to values from opts.

The created file includes:

Version comment at the top (current ascii-chat version)
All supported configuration sections with values from opts
Comments explaining each option

Note: The function will create the directory structure if needed.; If the file already exists, it will not be overwritten (returns error).

Definition at line 999 of file config.c.

                                                                                        {
  char *config_path_expanded = NULL;
  defer(SAFE_FREE(config_path_expanded));
 
  if (config_path) {
    // Use custom path provided
    config_path_expanded = expand_path(config_path);
    if (!config_path_expanded) {
      // If expansion fails, try using as-is (might already be absolute)
      config_path_expanded = platform_strdup(config_path);
    }
  } else {
    // Use default location with XDG support
    char *config_dir = get_config_dir();
    defer(SAFE_FREE(config_dir));
    if (config_dir) {
      size_t len = strlen(config_dir) + strlen("config.toml") + 1;
      config_path_expanded = SAFE_MALLOC(len, char *);
      if (config_path_expanded) {
#ifdef _WIN32
        safe_snprintf(config_path_expanded, len, "%sconfig.toml", config_dir);
#else
        safe_snprintf(config_path_expanded, len, "%sconfig.toml", config_dir);
#endif
      }
    }
 
    // Fallback to ~/.ascii-chat/config.toml
    if (!config_path_expanded) {
      config_path_expanded = expand_path("~/.ascii-chat/config.toml");
    }
  }
 
  if (!config_path_expanded) {
    return SET_ERRNO(ERROR_CONFIG, "Failed to resolve config file path");
  }
 
  char *validated_config_path = NULL;
  asciichat_error_t validate_result =
      path_validate_user_path(config_path_expanded, PATH_ROLE_CONFIG_FILE, &validated_config_path);
  if (validate_result != ASCIICHAT_OK) {
    SAFE_FREE(config_path_expanded);
    return validate_result;
  }
  SAFE_FREE(config_path_expanded);
  config_path_expanded = validated_config_path;
 
  // Check if file already exists
  struct stat st;
  if (stat(config_path_expanded, &st) == 0) {
    // File exists - ask user if they want to overwrite
    log_plain_stderr("Config file already exists: %s", config_path_expanded);
 
    bool overwrite = platform_prompt_yes_no("Overwrite", false); // Default to No
    if (!overwrite) {
      log_plain_stderr("Config file creation cancelled.");
      return SET_ERRNO(ERROR_CONFIG, "User cancelled overwrite");
    }
 
    // User confirmed overwrite - continue to create file (will overwrite existing)
    log_plain_stderr("Overwriting existing config file...");
  }
 
  // Create directory if needed
  char *dir_path = platform_strdup(config_path_expanded);
  if (!dir_path) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for directory path");
  }
 
  // Find the last path separator
  char *last_sep = strrchr(dir_path, PATH_DELIM);
 
  if (last_sep) {
    *last_sep = '\0';
    // Create directory (similar to known_hosts.c approach)
#ifdef _WIN32
    // Windows: Create directory (creates only one level)
    int mkdir_result = _mkdir(dir_path);
#else
    // POSIX: Create directory with DIR_PERM_PRIVATE permissions
    int mkdir_result = mkdir(dir_path, DIR_PERM_PRIVATE);
#endif
    if (mkdir_result != 0 && errno != EEXIST) {
      // mkdir failed and it's not because the directory already exists
      // Verify if directory actually exists despite the error (Windows compatibility)
      struct stat test_st;
      if (stat(dir_path, &test_st) != 0) {
        // Directory doesn't exist and we couldn't create it
        asciichat_error_t err = SET_ERRNO_SYS(ERROR_CONFIG, "Failed to create config directory: %s", dir_path);
        SAFE_FREE(dir_path);
        return err;
      }
      // Directory exists despite error, proceed
    }
  }
  SAFE_FREE(dir_path);
 
  // Create file with default values
  FILE *f = platform_fopen(config_path_expanded, "w");
  defer(SAFE_FCLOSE(f));
  if (!f) {
    return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to create config file: %s", config_path_expanded);
  }
 
  // Write version comment
  (void)fprintf(f, "# ascii-chat configuration file\n");
  (void)fprintf(f, "# Generated by ascii-chat v%d.%d.%d-%s\n", ASCII_CHAT_VERSION_MAJOR, ASCII_CHAT_VERSION_MINOR,
                ASCII_CHAT_VERSION_PATCH, ASCII_CHAT_GIT_VERSION);
  (void)fprintf(f, "#\n");
  (void)fprintf(f, "# If you upgrade ascii-chat and this version comment changes, you may need to\n");
  (void)fprintf(f, "# delete and regenerate this file with: ascii-chat --config-create\n");
  (void)fprintf(f, "#\n\n");
 
  // Write network section with defaults
  (void)fprintf(f, "[network]\n");
  (void)fprintf(f, "# Port number (1-65535, shared between server and client)\n");
  (void)fprintf(f, "#port = %s\n\n", opts->port);
 
  // Write server section with bind addresses
  (void)fprintf(f, "[server]\n");
  (void)fprintf(f, "# IPv4 bind address (default: 127.0.0.1)\n");
  (void)fprintf(f, "#bind_ipv4 = \"127.0.0.1\"\n");
  (void)fprintf(f, "# IPv6 bind address (default: ::1 for IPv6-only, or :: for dual-stack)\n");
  (void)fprintf(f, "#bind_ipv6 = \"::1\"\n");
  (void)fprintf(f, "# Legacy bind address (fallback if bind_ipv4/bind_ipv6 not set)\n");
  (void)fprintf(f, "#address = \"::\"\n\n");
 
  // Write client section with defaults
  (void)fprintf(f, "[client]\n");
  (void)fprintf(f, "# Server address to connect to\n");
  (void)fprintf(f, "#address = \"%s\"\n", opts->address);
  (void)fprintf(f, "# Alternative: set via network.address (legacy)\n");
  (void)fprintf(f, "#network.address = \"%s\"\n\n", opts->address);
  (void)fprintf(f, "# Terminal width in characters (0 = auto-detect)\n");
  (void)fprintf(f, "#width = %hu\n", opts->width);
  (void)fprintf(f, "# Terminal height in characters (0 = auto-detect)\n");
  (void)fprintf(f, "#height = %hu\n", opts->height);
  (void)fprintf(f, "# Webcam device index (0 = first webcam)\n");
  (void)fprintf(f, "#webcam_index = %hu\n", opts->webcam_index);
  (void)fprintf(f, "# Flip webcam image horizontally\n");
  (void)fprintf(f, "#webcam_flip = %s\n", opts->webcam_flip ? "true" : "false");
  (void)fprintf(f, "# Color mode: \"none\", \"16\", \"256\", \"truecolor\" (or \"auto\" for auto-detect)\n");
  (void)fprintf(f, "#color_mode = \"auto\"\n");
  (void)fprintf(f, "# Render mode: \"foreground\", \"background\", \"half-block\"\n");
  (void)fprintf(f, "#render_mode = \"foreground\"\n");
  (void)fprintf(f, "# Frames per second (1-144, default: 30 for Windows, 60 for Unix)\n");
#if defined(_WIN32)
  (void)fprintf(f, "#fps = 30\n");
#else
  (void)fprintf(f, "#fps = 60\n");
#endif
  (void)fprintf(f, "# Stretch video to terminal size (without preserving aspect ratio)\n");
  (void)fprintf(f, "#stretch = %s\n", opts->stretch ? "true" : "false");
  (void)fprintf(f, "# Quiet mode (disable console logging)\n");
  (void)fprintf(f, "#quiet = %s\n", opts->quiet ? "true" : "false");
  (void)fprintf(f, "# Snapshot mode (capture one frame and exit)\n");
  (void)fprintf(f, "#snapshot_mode = %s\n", opts->snapshot_mode ? "true" : "false");
  (void)fprintf(f, "# Snapshot delay in seconds (for webcam warmup)\n");
  (void)fprintf(f, "#snapshot_delay = %.1f\n", (double)opts->snapshot_delay);
  (void)fprintf(f, "# Use test pattern instead of real webcam\n");
  (void)fprintf(f, "#test_pattern = %s\n", opts->test_pattern ? "true" : "false");
  (void)fprintf(f, "# Show terminal capabilities and exit\n");
  (void)fprintf(f, "#show_capabilities = %s\n", opts->show_capabilities ? "true" : "false");
  (void)fprintf(f, "# Force UTF-8 support\n");
  (void)fprintf(f, "#force_utf8 = %s\n\n", opts->force_utf8 ? "true" : "false");
 
  // Write audio section (client only)
  (void)fprintf(f, "[audio]\n");
  (void)fprintf(f, "# Enable audio streaming\n");
  (void)fprintf(f, "#enabled = %s\n", opts->audio_enabled ? "true" : "false");
  (void)fprintf(f, "# Microphone device index (-1 = use default)\n");
  (void)fprintf(f, "#microphone_index = %d\n", opts->microphone_index);
  (void)fprintf(f, "# Speakers device index (-1 = use default)\n");
  (void)fprintf(f, "#speakers_index = %d\n\n", opts->speakers_index);
 
  // Write palette section
  (void)fprintf(f, "[palette]\n");
  (void)fprintf(f, "# Palette type: \"blocks\", \"half-blocks\", \"chars\", \"custom\"\n");
  (void)fprintf(f, "#type = \"half-blocks\"\n");
  (void)fprintf(f, "# Custom palette characters (only used if type = \"custom\")\n");
  (void)fprintf(f, "#chars = \"   ...',;:clodxkO0KXNWM\"\n\n");
 
  // Write crypto section
  (void)fprintf(f, "[crypto]\n");
  (void)fprintf(f, "# Enable encryption\n");
  (void)fprintf(f, "#encrypt_enabled = %s\n", opts->encrypt_enabled ? "true" : "false");
  (void)fprintf(f, "# Encryption key identifier (e.g., \"gpg:keyid\" or \"github:username\")\n");
  (void)fprintf(f, "#key = \"%s\"\n", opts->encrypt_key);
  (void)fprintf(f, "# Password for encryption (WARNING: storing passwords in config files is insecure!)\n");
  (void)fprintf(f, "# Use CLI --password or environment variables instead.\n");
  (void)fprintf(f, "#password = \"%s\"\n", opts->password);
  (void)fprintf(f, "# Key file path\n");
  (void)fprintf(f, "#keyfile = \"%s\"\n", opts->encrypt_keyfile);
  (void)fprintf(f, "# Disable encryption (opt-out)\n");
  (void)fprintf(f, "#no_encrypt = %s\n", opts->no_encrypt ? "true" : "false");
  (void)fprintf(f, "# Server public key (client only)\n");
  (void)fprintf(f, "#server_key = \"%s\"\n", opts->server_key);
  (void)fprintf(f, "# Client keys directory (server only)\n");
  (void)fprintf(f, "#client_keys = \"%s\"\n\n", opts->client_keys);
 
  // Write logging section
  (void)fprintf(f, "[logging]\n");
  (void)fprintf(f, "# Log file path (empty string = no file logging)\n");
  (void)fprintf(f, "#log_file = \"%s\"\n", opts->log_file);
 
  return ASCIICHAT_OK;
}

References options_state::address, ASCIICHAT_OK, options_state::audio_enabled, options_state::client_keys, defer, DIR_PERM_PRIVATE, options_state::encrypt_enabled, options_state::encrypt_key, options_state::encrypt_keyfile, errno, ERROR_CONFIG, ERROR_MEMORY, expand_path(), options_state::force_utf8, get_config_dir(), options_state::height, options_state::log_file, log_plain_stderr, options_state::microphone_index, options_state::no_encrypt, options_state::password, PATH_DELIM, PATH_ROLE_CONFIG_FILE, path_validate_user_path(), platform_fopen(), platform_prompt_yes_no(), platform_strdup(), options_state::port, options_state::quiet, SAFE_FCLOSE, SAFE_FREE, SAFE_MALLOC, safe_snprintf(), options_state::server_key, SET_ERRNO, SET_ERRNO_SYS, options_state::show_capabilities, options_state::snapshot_delay, options_state::snapshot_mode, options_state::speakers_index, options_state::stretch, options_state::test_pattern, options_state::webcam_flip, options_state::webcam_index, and options_state::width.

Referenced by options_init().

◆ config_load_and_apply()

asciichat_error_t config_load_and_apply	(	bool	is_client,
		const char *	config_path,
		bool	strict,
		options_t *	opts
	)

#include <config.c>

Main function to load configuration from file and apply to global options.

Load configuration from TOML file and apply to global options.

Parameters

is_client	`true` if loading client configuration, `false` for server configuration
config_path	Optional path to config file (NULL uses default location)
strict	If true, errors are fatal; if false, errors are non-fatal warnings

Returns: ASCIICHAT_OK on success, error code on failure (if strict) or non-fatal (if !strict)

This is the main entry point for configuration loading. It:

Expands the config file path (default location or custom path)
Checks if the file exists and is a regular file
Parses the TOML file using tomlc17
Applies configuration from each section (network, client, palette, crypto, logging)
Frees resources and returns

Configuration file errors are non-fatal if strict is false:

Missing file: Returns ASCIICHAT_OK (config file is optional)
Not a regular file: Warns and returns ASCIICHAT_OK
Parse errors: Warns and returns ASCIICHAT_OK
Invalid values: Individual values are skipped with warnings

If strict is true, any error causes immediate return with error code.

Note: This function should be called before options_init() parses command-line arguments to ensure CLI arguments can override config file values.; Configuration warnings are printed to stderr because logging may not be initialized yet when this function is called.

Parameters

is_client	`true` if loading client configuration, `false` for server configuration
config_path	Optional path to config file (NULL uses default location)
strict	If true, errors are fatal; if false, errors are non-fatal warnings

Returns: ASCIICHAT_OK on success, error code on failure (if strict) or non-fatal (if !strict)

Loads configuration from the specified path (or default location if config_path is NULL) and applies values to global options.

Default config file location (when config_path is NULL):

Unix: $XDG_CONFIG_HOME/ascii-chat/config.toml if set, otherwise ~/.ascii-chat/config.toml
Windows: APPDATA%\ascii-chat\config.toml if set, otherwise ~.ascii-chat\config.toml

Only applies configuration values that haven't already been set (though in practice, CLI arguments will override config values anyway since this is called before CLI parsing).

Supported configuration sections:

[network]: port
[server]: bind_ipv4, bind_ipv6
[client]: address, width, height, webcam_index, webcam_flip, color_mode, render_mode, fps, stretch, quiet, snapshot_mode, snapshot_delay, test_pattern, show_capabilities, force_utf8
[audio]: enabled, device
[palette]: type, chars
[crypto]: encrypt_enabled, key, password, keyfile, no_encrypt, server_key (client only), client_keys (server only)
[logging] or root: log_file

Note: This function should be called before options_init() parses command-line arguments, so that CLI arguments can override config file values.; If strict is false and the config file doesn't exist, is not a regular file, or fails to parse, the function returns ASCIICHAT_OK (non-fatal). Individual invalid values are skipped with warnings, but valid values are still applied.; If strict is true, any error (file not found, parse error, etc.) causes the function to return an error code immediately.

Warning: Configuration warnings are printed directly to stderr because logging may not be initialized yet when this function is called.

Definition at line 842 of file config.c.

                                                                                                               {
  char *config_path_expanded = NULL;
  defer(SAFE_FREE(config_path_expanded));
 
  if (config_path) {
    // Use custom path provided
    config_path_expanded = expand_path(config_path);
    if (!config_path_expanded) {
      // If expansion fails, try using as-is (might already be absolute)
      config_path_expanded = platform_strdup(config_path);
    }
  } else {
    // Use default location with XDG support
    char *config_dir = get_config_dir();
    defer(SAFE_FREE(config_dir));
    if (config_dir) {
      size_t len = strlen(config_dir) + strlen("config.toml") + 1;
      config_path_expanded = SAFE_MALLOC(len, char *);
      if (config_path_expanded) {
#ifdef _WIN32
        safe_snprintf(config_path_expanded, len, "%sconfig.toml", config_dir);
#else
        safe_snprintf(config_path_expanded, len, "%sconfig.toml", config_dir);
#endif
      }
    }
 
    // Fallback to ~/.ascii-chat/config.toml
    if (!config_path_expanded) {
      config_path_expanded = expand_path("~/.ascii-chat/config.toml");
    }
  }
 
  if (!config_path_expanded) {
    if (strict) {
      return SET_ERRNO(ERROR_CONFIG, "Failed to resolve config file path");
    }
    return ASCIICHAT_OK;
  }
 
  char *validated_config_path = NULL;
  asciichat_error_t validate_result =
      path_validate_user_path(config_path_expanded, PATH_ROLE_CONFIG_FILE, &validated_config_path);
  if (validate_result != ASCIICHAT_OK) {
    return validate_result;
  }
  SAFE_FREE(config_path_expanded);
  config_path_expanded = validated_config_path;
 
  // Determine display path for error messages (before any early returns)
  const char *display_path = config_path ? config_path : config_path_expanded;
 
  // Check if config file exists
  struct stat st;
  if (stat(config_path_expanded, &st) != 0) {
    if (strict) {
      return SET_ERRNO(ERROR_CONFIG, "Config file does not exist: '%s'", display_path);
    }
    // File doesn't exist, that's OK - not required (non-strict mode)
    return ASCIICHAT_OK;
  }
 
  // Verify it's a regular file
  if (!S_ISREG(st.st_mode)) {
    if (strict) {
      return SET_ERRNO(ERROR_CONFIG, "Config file exists but is not a regular file: '%s'", display_path);
    }
    CONFIG_WARN("Config file exists but is not a regular file: '%s' (skipping)", display_path);
    return ASCIICHAT_OK;
  }
 
  // Parse TOML file
  toml_result_t result = toml_parse_file_ex(config_path_expanded);
  defer(toml_free(result));
 
  if (!result.ok) {
    // result.errmsg is an array, so check its first character
    const char *errmsg = (strlen(result.errmsg) > 0) ? result.errmsg : "Unknown parse error";
 
    if (strict) {
      // For strict mode, return detailed error message directly
      // Note: SET_ERRNO stores the message in context, but asciichat_error_string() only returns generic codes
      // So we need to format the error message ourselves here
      char error_buffer[512];
      safe_snprintf(error_buffer, sizeof(error_buffer), "Failed to parse config file '%s': %s", display_path, errmsg);
      return SET_ERRNO(ERROR_CONFIG, "%s", error_buffer);
    }
    CONFIG_WARN("Failed to parse config file '%s': %s (skipping)", display_path, errmsg);
    return ASCIICHAT_OK; // Non-fatal error
  }
 
  // Apply configuration from each section
  apply_network_config(result.toptab, is_client, opts);
  apply_client_config(result.toptab, is_client, opts);
  apply_audio_config(result.toptab, is_client, opts);
  apply_palette_config_from_toml(result.toptab, opts);
  asciichat_error_t crypto_result = apply_crypto_config(result.toptab, is_client, opts);
  if (crypto_result != ASCIICHAT_OK) {
    return crypto_result;
  }
  asciichat_error_t log_result = apply_log_config(result.toptab, opts);
  if (log_result != ASCIICHAT_OK) {
    return log_result;
  }
 
  // Reset all config flags for next call
  config_address_set = false;
  config_address6_set = false;
  config_port_set = false;
  config_width_set = false;
  config_height_set = false;
  config_webcam_index_set = false;
  config_webcam_flip_set = false;
  config_color_mode_set = false;
  config_render_mode_set = false;
  config_palette_set = false;
  config_palette_chars_set = false;
  config_audio_enabled_set = false;
  config_microphone_index_set = false;
  config_speakers_index_set = false;
  config_stretch_set = false;
  config_quiet_set = false;
  config_snapshot_mode_set = false;
  config_mirror_mode_set = false;
  config_snapshot_delay_set = false;
  config_log_file_set = false;
  config_encrypt_enabled_set = false;
  config_encrypt_key_set = false;
  config_password_set = false;
  config_encrypt_keyfile_set = false;
  config_no_encrypt_set = false;
  config_server_key_set = false;
  config_client_keys_set = false;
 
  CONFIG_DEBUG("Loaded configuration from %s", display_path);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONFIG_DEBUG, CONFIG_WARN, defer, ERROR_CONFIG, expand_path(), get_config_dir(), PATH_ROLE_CONFIG_FILE, path_validate_user_path(), platform_strdup(), SAFE_FREE, SAFE_MALLOC, safe_snprintf(), and SET_ERRNO.

Referenced by config_load_system_and_user().

◆ config_load_system_and_user()

asciichat_error_t config_load_system_and_user	(	bool	is_client,
		const char *	user_config_path,
		bool	strict,
		options_t *	opts
	)

#include <config.h>

Load system config first, then user config (user config overrides system)

Parameters

is_client	`true` if loading client configuration, `false` for server configuration
user_config_path	Optional path to user config file (NULL uses default location)
strict	If true, user config errors are fatal; system config is always non-strict
opts	Options structure to write configuration to

Returns: ASCIICHAT_OK on success, error code on failure

Loads configuration from two locations in order:

System config: ${INSTALL_PREFIX}/etc/ascii-chat/config.toml (non-strict, optional)
User config: custom path or default location (strictness as specified)

User config values override system config values. Both override defaults. This function should be called before options_init() parses command-line arguments.

Note: System config is always loaded non-strict (missing file is not an error); User config strictness follows the strict parameter

Definition at line 1207 of file config.c.

                                                               {
  // Fallback for ASCIICHAT_INSTALL_PREFIX if paths.h hasn't been generated yet
  // (prevents defer tool compilation errors during initial builds)
#ifndef ASCIICHAT_INSTALL_PREFIX
#define ASCIICHAT_INSTALL_PREFIX "/usr"
#endif
 
  // Build system config path: ${INSTALL_PREFIX}/etc/ascii-chat/config.toml
  char system_config_path[1024];
#ifdef _WIN32
  SAFE_SNPRINTF(system_config_path, sizeof(system_config_path), "%s\\etc\\ascii-chat\\config.toml",
                ASCIICHAT_INSTALL_PREFIX);
#else
  SAFE_SNPRINTF(system_config_path, sizeof(system_config_path), "%s/etc/ascii-chat/config.toml",
                ASCIICHAT_INSTALL_PREFIX);
#endif
 
  // Load system config first (non-strict - it's optional)
  CONFIG_DEBUG("Attempting to load system config from: %s", system_config_path);
  asciichat_error_t system_result = config_load_and_apply(is_client, system_config_path, false, opts);
  if (system_result == ASCIICHAT_OK) {
    CONFIG_DEBUG("System config loaded successfully");
  } else {
    CONFIG_DEBUG("System config not loaded (this is normal if file doesn't exist)");
    // Clear the error context since this failure is expected/non-fatal
    CLEAR_ERRNO();
  }
 
  // Load user config second (with user-specified strictness)
  // User config values will override system config values
  CONFIG_DEBUG("Loading user config (strict=%s)", strict ? "true" : "false");
  asciichat_error_t user_result = config_load_and_apply(is_client, user_config_path, strict, opts);
 
  // Return user config result - errors in user config should be reported
  return user_result;
}

References ASCIICHAT_INSTALL_PREFIX, ASCIICHAT_OK, CLEAR_ERRNO, CONFIG_DEBUG, config_load_and_apply(), and SAFE_SNPRINTF.

Referenced by options_init().

Files

Functions

Detailed Description

Configuration README

Overview

TOML Configuration Files

File Format

Loading Configuration

Command-Line Options

Server Options

Client Options

Common Options

Default Config Locations

Configuration Precedence

Configuration Validation

Usage Examples

Parsing Command-Line and Config File

Setting Defaults

Function Documentation

◆ config_create_default()

◆ config_load_and_apply()

◆ config_load_system_and_user()