🛠️ String, path, IP, UTF-8, CRC32, and formatting utilities More...

Files
file	atomic.c
	Implementation of atomic operations abstraction.

file	musl_c23_compat.c
	🔄 musl C23 compatibility wrappers for __isoc23_* symbol aliases (glibc 2.38+ compatibility)

file	crc32.c
	⚡ Hardware-accelerated CRC32 checksum with ARM64 and x86_64 CPU feature detection

file	aspect_ratio.c
	📐 Terminal cell aspect ratio calculations for accurate image dimension scaling

file	format.c
	📊 Byte size formatting utilities for human-readable output (B, KB, MB, GB, TB, PB, EB)

file	image.c
	🖼️ Safe overflow-checked buffer size calculations for images and video frames

file	ip.c
	🌍 IPv4/IPv6 address parsing, validation, and formatting utilities

file	parsing.c
	🔍 Safe string parsing utilities for integers, sizes, and protocol messages

file	password.c
	🔑 Password prompting utilities with secure input and formatting

file	path.c
	Cross-platform path manipulation with normalization and Windows/Unix separator handling.

file	pcre2.c
	Centralized PCRE2 singleton pattern for efficient regex compilation.

file	string.c
	🔤 String manipulation utilities: ASCII escaping, trimming, case conversion, and formatting

file	url.c
	Production-grade URL parsing and validation using PCRE2.

file	utf8.c
	🔤 UTF-8 encoding and decoding with multi-byte character support

file	version.c
	🏷️ Binary-embedded version information in custom ELF/Mach-O sections for runtime inspection

file	atomic.h
	⚛️ Atomic operations abstraction layer with debug tracking

file	crc32.h
	Hardware-Accelerated CRC32 Checksum Computation.

file	aspect_ratio.h
	📐 Aspect Ratio Calculation Functions

file	bits.h
	🔢 Bit Manipulation Utilities

file	bytes.h
	🔢 Byte-Level Access and Arithmetic Utilities

file	display.h
	🖥️ Display Width and Terminal Centering Utilities

file	endian.h
	🔄 Network byte order conversion helpers

file	fnv1a.h
	#️⃣ FNV-1a Hash Function Implementation

file	format.h
	📊 String Formatting Utilities

file	image.h
	🖼️ Safe overflow-checked buffer size calculations for images and video frames

file	ip.h
	🌍 IP Address Parsing and Formatting Utilities

file	magic.h
	Magic number validation constants and macros.

file	math.h
	🔢 Mathematical Utility Functions

file	number.h
	🔢 Number Formatting and Conversion Utilities

file	overflow.h
	✅ Safe Integer Arithmetic and Overflow Detection

file	parsing.h
	🔍 Safe Parsing Utilities

file	password.h
	Password prompting utilities with secure input and formatting.

file	path.h
	📂 Path Manipulation Utilities

file	pcre2.h
	🔍 Centralized PCRE2 singleton pattern for efficient regex compilation

file	string.h
	🔤 String Manipulation and Shell Escaping Utilities

file	thread.h
	🧵 Thread lifecycle management helpers

file	url.h
	🌐 Production-Grade URL Validation and Parsing

file	utf8.h
	🔤 UTF-8 Encoding and Decoding Utilities

file	util.h
	🛠️ Master Utility Header

Data Structures
struct	atomic_t
	Atomic value wrapper for integral/boolean types. More...

struct	atomic_ptr_t
	Atomic pointer wrapper. More...

struct	url_parts_t
	Structure containing parsed URL components. More...

Macros
#define	asciichat_crc32(data, len) asciichat_crc32_hw((data), (len))
	Main CRC32 dispatcher macro - use this in application code.

#define	FNV1A_32_OFFSET_BASIS 2166136261ULL
	FNV-1a 32-bit offset basis.

#define	FNV1A_32_PRIME 16777619ULL
	FNV-1a 32-bit prime.

#define	FNV1A_32_MASK 0xFFFFFFFFULL
	FNV-1a 32-bit mask.

#define	FNV1A_INIT(hash) uint64_t hash = FNV1A_32_OFFSET_BASIS;
	FNV-1a 32-bit hash macro.

#define	FNV1A_32_HASH(hash, byte)
	FNV-1a 32-bit hash macro for a single byte.

#define	ROUND(xfloat) (int)(0.5f + (xfloat))
	Round floating-point value to nearest integer.

#define	SIZE_MUL_SAFE(a, b) (size_mul_would_overflow(a, b) ? SIZE_MAX : (a) * (b))
	Multiply with overflow check inline (macro form for tight loops)

#define	SIZE_ADD_SAFE(a, b) (size_add_would_overflow(a, b) ? SIZE_MAX : (a) + (b))
	Add with overflow check inline (macro form for tight loops)

#define	PASSWORD_MAX_LEN 260
	Buffer size for password input.

#define	PATH_COMPONENT_DOT '.'
	Path component: current directory (single dot)

#define	PATH_COMPONENT_DOTDOT ".."
	Path component: parent directory (double dot)

#define	PATH_TILDE '~'
	Path component: home directory tilde.

#define	PATH_DRIVE_SEPARATOR ':'
	Path component: Windows drive separator (colon)

#define	MAX_PATH_BASES 16
	Maximum number of path base directories.

Enumerations
enum	path_role_t { PATH_ROLE_CONFIG_FILE , PATH_ROLE_LOG_FILE , PATH_ROLE_KEY_PRIVATE , PATH_ROLE_KEY_PUBLIC , PATH_ROLE_CLIENT_KEYS }
	Classification for user-supplied filesystem paths. More...

Functions
long	__isoc23_wcstol (const wchar_t str, wchar_t *endptr, int base)
	Wide string to integer conversion.

int	__isoc23_scanf (const char *format,...)
	Formatted input functions.

int	__isoc23_wscanf (const wchar_t *format,...)
	Wide character formatted input functions.

void	arc4random_buf (void *buf, size_t nbytes)
	glibc-specific random functions for expat and fontconfig compatibility

uint32_t	asciichat_crc32_hw (const void *data, size_t len)
	Compute CRC32 checksum with hardware acceleration (if available)

uint32_t	asciichat_crc32_sw (const void *data, size_t len)
	Compute CRC32 checksum using software implementation only.

bool	crc32_hw_is_available (void)
	Check if hardware CRC32 acceleration is available at runtime.

void	aspect_ratio (const ssize_t img_width, const ssize_t img_height, const ssize_t width, const ssize_t height, const bool stretch, ssize_t out_width, ssize_t out_height)
	Calculate aspect ratio with terminal character correction.

void	aspect_ratio2 (const ssize_t img_width, const ssize_t img_height, const ssize_t target_width, const ssize_t target_height, ssize_t out_width, ssize_t out_height)
	Simple aspect ratio calculation without terminal character correction.

void	calculate_fit_dimensions_pixel (int img_width, int img_height, int max_width, int max_height, int out_width, int out_height)
	Calculate fit dimensions for pixel-based images.

int	display_width (const char *text)
	Calculate the visible display width of text with ANSI escape codes.

int	display_center_horizontal (const char *text, int terminal_width)
	Calculate left padding needed to center text horizontally.

int	display_center_vertical (int content_height, int terminal_height)
	Calculate top padding needed to vertically center content.

int	display_height (const char *text, int terminal_width)
	Calculate how many display lines text will consume when wrapped.

void	format_bytes_pretty (size_t bytes, char *out, size_t out_capacity)
	Format byte count into human-readable string.

int	is_valid_ipv4 (const char *ip)
	Check if a string is a valid IPv4 address.

int	is_valid_ipv6 (const char *ip)
	Check if a string is a valid IPv6 address.

int	parse_ipv6_address (const char input, char output, size_t output_size)
	Parse IPv6 address, removing brackets if present.

int	parse_ip_with_port (const char input, char ip_output, size_t ip_output_size, uint16_t *port_output)
	Parse IP address and port from string.

int	parse_address_with_optional_port (const char input, char address_output, size_t address_output_size, uint16_t *port_output, uint16_t default_port)
	Parse address with optional port from string.

asciichat_error_t	format_ip_address (int family, const struct sockaddr addr, char output, size_t output_size)
	Format IP address from socket address structure.

asciichat_error_t	format_ip_with_port (const char ip, uint16_t port, char output, size_t output_size)
	Format IP address with port number.

int	get_ip_version (const char *ip)
	Get IP address version.

int	is_valid_ip (const char *ip)
	Check if string is a valid IP address (IPv4 or IPv6)

int	ip_equals (const char ip1, const char ip2)
	Compare two IP addresses for equality.

int	ip_compare (const char ip1, const char ip2)
	Compare two IP addresses for sorting.

int	compare_ip_port_strings (const char ip_port1, const char ip_port2)
	Compare two "IP:port" strings with IPv6 normalization.

int	parse_cidr (const char cidr, char ip_out, size_t ip_out_size, int *prefix_out)
	Parse CIDR notation into IP and prefix length.

int	ip_in_cidr (const char ip, const char cidr)
	Check if IP address is within CIDR range.

int	ip_in_cidr_parsed (const char ip, const char network, int prefix_len)
	Check if IP is within CIDR range (parsed form)

asciichat_error_t	ipv4_to_ipv6_mapped (const char ipv4, char ipv6_out, size_t out_size)
	Convert IPv4 address to IPv6-mapped format.

asciichat_error_t	extract_ipv4_from_mapped_ipv6 (const char ipv6, char ipv4_out, size_t out_size)
	Extract IPv4 address from IPv6-mapped format.

int	is_ipv4_mapped_ipv6 (const char *ipv6)
	Check if IPv6 address is IPv4-mapped.

asciichat_error_t	canonicalize_ipv6 (const char ipv6, char canonical_out, size_t out_size)
	Canonicalize IPv6 address to standard form.

asciichat_error_t	expand_ipv6 (const char ipv6, char expanded_out, size_t out_size)
	Expand IPv6 address to full form.

asciichat_error_t	compact_ipv6 (const char ipv6, char compact_out, size_t out_size)
	Compress IPv6 address using :: notation.

int	is_anycast_ipv6 (const char *ipv6)
	Check if IPv6 address is anycast.

int	is_lan_ipv4 (const char *ip)
	Check if IPv4 address is a private/LAN address.

int	is_lan_ipv6 (const char *ip)
	Check if IPv6 address is a private/LAN address.

int	is_broadcast_ipv4 (const char *ip)
	Check if IPv4 address is a broadcast address.

int	is_broadcast_ipv6 (const char *ip)
	Check if IPv6 address is a multicast address.

int	is_localhost_ipv4 (const char *ip)
	Check if IPv4 address is localhost.

int	is_localhost_ipv6 (const char *ip)
	Check if IPv6 address is localhost.

int	is_link_local_ipv4 (const char *ip)
	Check if IPv4 address is a link-local address.

int	is_link_local_ipv6 (const char *ip)
	Check if IPv6 address is a link-local address.

int	is_internet_ipv4 (const char *ip)
	Check if IPv4 address is a public internet address.

int	is_internet_ipv6 (const char *ip)
	Check if IPv6 address is a public internet address.

int	extract_ip_from_address (const char addr_with_port, char ip_out, size_t ip_out_size)
	Extract IP address (without port) from formatted address string.

const char *	get_ip_type_string (const char *ip)
	Get human-readable string describing IP address type.

asciichat_error_t	safe_parse_size_message (const char message, unsigned int width, unsigned int *height)
	Parse SIZE message format.

asciichat_error_t	safe_parse_audio_message (const char message, unsigned int num_samples)
	Parse AUDIO message format.

int	prompt_password (const char prompt, char password, size_t max_len)
	Prompt the user for a password with secure input.

int	prompt_password_simple (const char prompt, char password, size_t max_len)
	Prompt the user for a password with simple formatting.

const char *	extract_project_relative_path (const char *file)
	Extract relative path from an absolute path.

char *	expand_path (const char *path)
	Expand path with tilde (~) support.

char *	get_config_dir (void)
	Get configuration directory path with XDG_CONFIG_HOME support.

char *	get_data_dir (void)
	Get application data directory path.

char *	get_log_dir (void)
	Get log directory path appropriate for current build type.

char *	get_discovery_database_dir (void)
	Get discovery service database directory with Homebrew-aware system-wide fallback.

bool	path_normalize_copy (const char path, char out, size_t out_len)
	Normalize a path and copy it into the provided buffer.

bool	path_is_absolute (const char *path)
	Determine whether a path is absolute on the current platform.

bool	path_is_within_base (const char path, const char base)
	Check whether a path resides within a specified base directory.

bool	path_is_within_any_base (const char path, const char const *bases, size_t base_count)
	Check whether a path resides within any of several base directories.

bool	path_looks_like_path (const char *value)
	Determine if a string is likely intended to reference the filesystem.

asciichat_error_t	path_validate_user_path (const char input, path_role_t role, char *normalized_out)
	Validate and canonicalize a user-supplied filesystem path.

void	path_cleanup_thread_locals (void)
	Cleanup thread-local path resources.

void	escape_ascii (const char str, const char escape_char, char *out_buffer, size_t out_buffer_size)
	Escape ASCII characters in a string.

bool	validate_shell_safe (const char str, const char allowed_chars)
	Validate that a string contains only safe characters for shell commands.

bool	escape_shell_single_quotes (const char str, char out_buffer, size_t out_buffer_size)
	Escape a string for safe use in shell commands (single quotes)

bool	escape_shell_double_quotes (const char str, char out_buffer, size_t out_buffer_size)
	Escape a string for safe use in shell commands (double quotes, Windows-compatible)

bool	string_needs_shell_quoting (const char *str)
	Check if a string needs shell quoting (contains spaces or special chars)

bool	escape_path_for_shell (const char path, char out_buffer, size_t out_buffer_size)
	Escape a path for safe use in shell commands (auto-platform)

const char *	colored_string (log_color_t color, const char *text)
	Build a colored string for terminal output.

void	truncate_with_ellipsis (const char input, char output, size_t output_size, int max_width)
	Truncate a string to a maximum display width, with ellipsis.

void	strip_ansi_codes (const char input, char output, size_t output_size)
	Strip ANSI escape codes from a string.

bool	url_is_valid (const char *url)
	Fast URL validation using production-grade regex (HTTP/HTTPS/WebSocket/TCP)

asciichat_error_t	url_parse (const char url, url_parts_t parts_out)
	Parse HTTP(S), WebSocket, and TCP URL into components.

void	url_parts_destroy (url_parts_t *parts)
	Free parsed URL components.

bool	url_is_websocket_scheme (const char *scheme)
	Check if URL scheme is WebSocket (ws or wss)

bool	url_is_websocket (const char *url)
	Check if a URL string is a valid WebSocket URL.

bool	url_looks_like_websocket (const char *url)
	Quick check if a string is a WebSocket URL.

bool	url_is_tcp_scheme (const char *scheme)
	Check if URL scheme is TCP.

bool	url_is_tcp (const char *url)
	Check if a URL string is a valid TCP URL.

bool	url_looks_like_tcp (const char *url)
	Quick check if a string is a TCP URL.

int	utf8_decode (const uint8_t s, uint32_t codepoint)
	Decode a UTF-8 sequence to a Unicode codepoint.

int	utf8_display_width (const char *str)
	Calculate terminal display width of a UTF-8 string.

int	utf8_display_width_n (const char *str, size_t max_bytes)
	Calculate terminal display width of a UTF-8 string up to byte limit.

bool	utf8_is_valid (const char *str)
	Check if a string is valid UTF-8.

bool	utf8_is_ascii_only (const char *str)
	Check if a string contains only ASCII characters.

size_t	utf8_char_count (const char *str)
	Count UTF-8 characters (not bytes)

size_t	utf8_to_codepoints (const char str, uint32_t out_codepoints, size_t max_codepoints)
	Convert UTF-8 string to array of Unicode codepoints.

int	utf8_next_char_bytes (const char *str, size_t max_bytes)
	Get byte length of next UTF-8 character.

int	utf8_continuation_bytes_needed (unsigned char first_byte)
	Determine how many additional bytes are needed to complete a UTF-8 character.

int	utf8_read_and_insert_continuation_bytes (char buffer, size_t cursor, size_t len, size_t max_len, int continuation_bytes, int(read_byte_fn)(void))
	Read continuation bytes and insert them into buffer at cursor position.

const char *	utf8_strcasestr (const char haystack, const char needle)
	Case-insensitive substring search with full Unicode support.

void	utf8_write_lowercase (FILE output, const char text)
	Write UTF-8 string to file with ASCII lowercase conversion.

Detailed Description

🛠️ String, path, IP, UTF-8, CRC32, and formatting utilities

This header provides CRC32 checksum computation with automatic hardware acceleration when available. The system automatically dispatches to hardware implementations (SSE4.2, ARM CRC32) for optimal performance, falling back to a software implementation on platforms without hardware support.

CORE FEATURES:

Automatic hardware acceleration detection
Hardware-accelerated CRC32 on supported platforms (SSE4.2, ARM)
Software fallback implementation (always available)
Transparent performance optimization
Used for network packet integrity verification

HARDWARE ACCELERATION:

The system supports:

SSE4.2 CRC32 instruction (x86/x64 processors)
ARM CRC32 instructions (ARMv8 and later)
Automatic runtime detection and dispatch
Significant performance improvement over software implementation

SOFTWARE FALLBACK:

Always available on all platforms
Polynomial: IEEE 802.3 (CRC-32)
Optimized lookup table implementation
Reliable for packet integrity verification

PERFORMANCE:

Hardware acceleration provides:

10-100x faster than software implementation
Zero overhead when hardware is available
Automatic fallback ensures compatibility

Note: Use the asciichat_crc32() macro for automatic hardware dispatch.; Hardware acceleration is detected at runtime, so no compile-time configuration is required.; CRC32 is used primarily for network packet integrity verification to detect transmission errors.

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

Date: October 2025

This header provides functions for calculating image dimensions while maintaining aspect ratio. Functions handle terminal character correction for ASCII art rendering and pixel-based calculations for image scaling.

CORE FEATURES:

Aspect ratio calculations with terminal character correction
Simple aspect ratio calculations without terminal correction
Image dimension fitting within maximum bounds
Stretch/no-stretch mode support
Pixel-based and character-based calculations

TERMINAL CHARACTER CORRECTION:

Terminal characters have different aspect ratios than square pixels:

Terminal characters are typically taller than wide (e.g., 2:1 ratio)
This correction ensures ASCII art maintains proper proportions
aspect_ratio() applies terminal correction automatically
aspect_ratio2() skips correction for pixel-based calculations

ASPECT RATIO CALCULATIONS:

Functions calculate dimensions that maintain image aspect ratio:

aspect_ratio(): With terminal character correction (for ASCII art)
aspect_ratio2(): Without terminal correction (simple pixel math)
calculate_fit_dimensions_pixel(): Fit image within maximum bounds

Note: Terminal character aspect ratio correction is essential for proper ASCII art rendering that matches the original image proportions.; All output parameters are modified only on successful calculation.; This file contains functions based on jp2a code: Copyright (C) 2006 Christian Stigen Larsen, http://csl.sublevel3.org Distributed under the GNU General Public License (GPL) v2. Project homepage on http://jp2a.sf.net

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

Date: October 2025

Portable bit manipulation functions including power-of-two checks, bit counting, and leading/trailing zero detection across platforms.

CORE FEATURES:

Power-of-two validation and rounding
Find first/last set bit (platform-optimized)
Bit counting operations

PLATFORM SUPPORT:

GCC/Clang: Uses built-in intrinsics for optimal performance
MSVC: Uses Windows intrinsic functions
Fallback: Software implementations for all operations

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

Date: December 2025

This header provides low-level utilities for safely reading and writing multi-byte values from/to unaligned memory addresses, with overflow detection for size calculations.

CORE FEATURES:

Safe unaligned memory access (16-bit and 32-bit values)
Safe size_t multiplication with overflow detection
Platform-safe byte manipulation (uses memcpy for portability)

UNALIGNED ACCESS:

Direct pointer casts like *(uint32_t*)ptr cause undefined behavior on architectures requiring aligned access (ARM, SPARC, etc.). These functions use memcpy which compilers optimize to single instructions when possible while remaining safe on all platforms.

Note: These functions are used extensively in network and crypto modules for parsing and generating packets.

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

Date: December 2025

This header provides a shared FNV-1a hash function implementation used throughout the codebase for consistent hashing with UBSan-safe arithmetic.

FNV-1a (Fowler-Noll-Vo) is a fast, non-cryptographic hash function with good distribution properties. This implementation uses 64-bit arithmetic to avoid unsigned overflow, then masks to 32-bit for the final result.

All functions are static inline for performance, allowing the compiler to inline them at call sites.

Note: This hash function is NOT for cryptographic purposes.; All arithmetic is done in 64-bit space to avoid UBSan warnings.

This header provides utilities for formatting various data types into human-readable strings. Functions handle byte counts, sizes, and other numeric values with appropriate units and formatting.

CORE FEATURES:

Byte count formatting with units (B, KB, MB, GB, TB)
Human-readable size strings
Automatic unit selection based on value
Fixed decimal precision
Buffer overflow protection

BYTE FORMATTING:

Byte counts are formatted with appropriate binary units:

Bytes (B): 0-1023 bytes
Kilobytes (KB): 1024-1048575 bytes
Megabytes (MB): 1048576-1073741823 bytes
Gigabytes (GB): 1073741824-1099511627775 bytes
Terabytes (TB): 1099511627776 and above

Note: All formatting functions ensure buffer overflow protection.; Output strings are null-terminated.; Decimal precision is fixed (2 decimal places for units >= KB).

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

Date: October 2025

This header provides utilities for validating, parsing, and formatting IPv4 and IPv6 addresses with proper bracket notation support. Functions handle various address formats including bracketed IPv6 addresses.

CORE FEATURES:

IPv4 address validation and parsing
IPv6 address validation and parsing
Bracket notation support for IPv6 ([::1])
IP address with port formatting and parsing
Hostname support (non-IP addresses)
Cross-platform compatibility

IP ADDRESS FORMATS:

The system supports various IP address formats:

IPv4: "192.0.2.1" (standard dotted decimal)
IPv6: "::1" or "[::1]" (with or without brackets)
IPv6: "2001:db8::1" or "[2001:db8::1]" (full format)
With port: "192.0.2.1:8080" or "[::1]:8080"

BRACKET NOTATION:

IPv6 addresses in URLs and socket addresses use bracket notation:

Format: "[2001:db8::1]:8080"
Brackets separate address from port (colons are part of IPv6 address)
parse_ipv6_address() removes brackets for internal use
format_ip_with_port() adds brackets for IPv6 addresses

Note: All parsing functions validate input addresses.; IPv6 addresses are normalized (brackets removed) for internal storage.; Port numbers are validated (0-65535 range).

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

Date: October 2025

This header provides lightweight mathematical utilities for image processing, including rounding and RGB value clamping.

CORE FEATURES:

RGB value clamping (0-255 range)
Floating-point to integer rounding

Note: For aspect ratio calculations, see util/aspect_ratio.h

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

Date: October 2025

Utilities for converting numbers to strings and calculating digit counts. Designed for minimal overhead, suitable for real-time video processing.

CORE FEATURES:

Digit counting for integers (no string allocation needed)
Decimal number to string conversion
Byte-to-string formatting (1-3 digits)
Fast and allocation-free implementations

USAGE:

// Count digits needed for allocation int digits = digits_u32(12345); // Returns 5 char buffer[digits]; size_t len = write_decimal(12345, buffer);

// Format u8 into ANSI sequence char ansi_seq[3]; char *end = write_u8(ansi_seq, 255); // Write "255" // ansi_seq now contains "255", end points after last char

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

Date: December 2025

Safe arithmetic operations that detect and handle integer overflow/underflow without undefined behavior. Essential for buffer size calculations and dimension validations to prevent security issues and crashes.

CORE FEATURES:

Safe multiplication with overflow detection
Safe addition with overflow detection
Checked size calculations (width * height * depth)
Clear error reporting

MOTIVATION:

Integer overflow in buffer size calculations is a common source of:

Buffer overflows (security vulnerability)
Crashes due to undersized allocations
Silent memory corruption

USAGE:

// Safe multiplication size_t result; if (checked_size_mul(width, height, &result) != ASCIICHAT_OK) { log_error("Dimension overflow: %zu x %zu", width, height); return ERROR_OVERFLOW; } uint8_t *buffer = SAFE_MALLOC(result, uint8_t *);

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

Date: December 2025

This header provides safe, validated parsing utilities for protocol message formats. Functions validate input strings, check for overflow conditions, and return structured error codes on failure.

CORE FEATURES:

Protocol message format parsing (SIZE, AUDIO)
Input validation and sanitization
Overflow protection for numeric values
Structured error reporting (asciichat_error_t)
Safe parsing without undefined behavior

PROTOCOL MESSAGE FORMATS:

The system supports parsing of ascii-chat protocol messages:

SIZE: "SIZE:width,height" - Video frame dimensions
AUDIO: "AUDIO:num_samples" - Audio sample count

VALIDATION:

All parsing functions validate:

Message format correctness
Numeric value ranges (no overflow)
Required fields presence
Delimiter correctness

Note: All parsing functions are safe and do not cause undefined behavior.; Invalid input returns error codes (ASCIICHAT_ERROR_*) for proper handling.; Output parameters are only modified on successful parsing.

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

Date: October 2025

Provides high-level password prompting functionality built on top of the platform question API. Includes formatting with visual separators and consistent user experience across the application.

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

Date: December 2025

This header provides cross-platform utilities for working with file paths, including path expansion, configuration directory resolution, and project relative path extraction.

Core Features

Cross-platform path handling (Unix and Windows)
Tilde (~) expansion for home directory
XDG_CONFIG_HOME support for configuration paths
Project relative path extraction for logging
Path normalization and validation

Path Expansion

The system supports:

Tilde expansion: ~/path -> /home/user/path
Environment variable expansion (Windows VAR%)
Automatic platform-specific path separator handling

Configuration Directories

All ascii-chat data files (config, known_hosts, etc.) use a single directory:

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

Note: All returned paths that require freeing are allocated with malloc() and must be freed by the caller using free().; Path operations handle both Unix (/) and Windows () separators.; Configuration paths include directory separator at the end.

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

Date: October 2025

This header provides utilities for string manipulation, shell command escaping, and validation. Functions ensure strings are safe for use in shell commands and command-line interfaces.

CORE FEATURES:

Shell-safe string validation
Single and double quote escaping
ASCII character escaping
Cross-platform shell compatibility (Unix shells and Windows cmd.exe)
Buffer overflow protection

SHELL ESCAPING:

The system provides different escaping strategies:

Single quotes: Escapes for Unix shells (sh, bash, zsh)
Double quotes: Escapes for Windows cmd.exe compatibility
ASCII escaping: Escapes specific characters for terminal output

SHELL METACHARACTERS:

The following characters are considered unsafe for shell commands:

Control characters: ; & | $ ‘ \ " ’ < > ( ) [ ] { } * ? ! ~ # @ - These characters can be used for command injection or shell expansion @note All escaping functions ensure buffer overflow protection. @note Escaped strings are safe for use in system() and popen() calls. @note Validation functions check for all common shell metacharacters. @author Zachary Fogg <me@zfo.gg> @date October 2025 This header provides robust URL validation and parsing using PCRE2 regular expressions. Based on the production-grade HTTP(S) URL regex by Diego Perini (MIT License), extended for WebSocket. <h1>CORE FEATURES: </h1> - Production-grade HTTP(S), WebSocket, and TCP URL validation via PCRE2 - Comprehensive URL parsing (extract scheme, host, port, path) - Scheme support: http, https, ws, wss, tcp (case-insensitive) - IPv4, IPv6, and hostname support (localhost, bare hosts, FQDNs) - Private IP filtering (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x) - JIT-compiled regex for 10-100x performance boost - Input validation and error reporting - Consistent error codes (asciichat_error_t) - Memory-safe operations <h1>USAGE EXAMPLES: </h1> Fast validation only (bool return): @code if (url_is_valid("https://github.com/user/repo")) { // URL is valid and can be safely used } @endcode Full parsing (extract components): @code url_parts_t parts = {0}; if (url_parse("https://api.github.com:443/users", &parts) == ASCIICHAT_OK) { printf("scheme: s, host: s, port: d, path: s\n", parts.scheme, parts.host, parts.port, parts.path); url_parts_destroy(&parts); }

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

Date: February 2026

Utility Functions

Overview

The Utility module provides a collection of helper functions and utilities used throughout ascii-chat. These include string manipulation, path handling, IP address parsing, mathematical operations, and format conversion.

Implementation: lib/util/*.h

Key Features:

Hardware-accelerated CRC32 checksums (SSE4.2, ARM CRC32)
Aspect ratio calculations and frame fitting
IP address parsing and validation (IPv4/IPv6)
UTF-8 string handling and validation
Path manipulation and normalization
String parsing and formatting utilities
Cross-platform mathematical operations

Utility Modules

CRC32 Checksums

Hardware Acceleration:

// CRC32 with automatic hardware acceleration
uint32_t checksum = crc32_compute(data, length);
 
// Check if hardware acceleration is available
if (crc32_hw_supported()) {
    log_info("Using hardware CRC32 acceleration");
}

Platforms:

x86/x64: SSE4.2 instructions (CRC32C)
ARM: ARM CRC32 instructions
Fallback: Software table-based CRC32

Aspect Ratio

Calculate Aspect Ratio:

// Calculate aspect ratio for fitting
int display_width = 80, display_height = 24;
int image_width = 1920, image_height = 1080;
 
dimensions_t fitted = fit_to_aspect_ratio(
    display_width, display_height,
    image_width, image_height
);
 
log_info("Fitted size: %dx%d", fitted.width, fitted.height);

Maintain Aspect Ratio:

// Get dimensions that maintain aspect ratio
dimensions_t dims = calculate_aspect_ratio_fit(
    src_width, src_height,
    dst_width, dst_height,
    maintain_aspect_ratio  // true/false
);

IP Address Utilities

Parse IP Addresses:

// Parse IPv4 address
struct in_addr addr4;
if (parse_ipv4("192.168.1.1", &addr4)) {
    log_info("Valid IPv4 address");
}
 
// Parse IPv6 address
struct in6_addr addr6;
if (parse_ipv6("::1", &addr6)) {
    log_info("Valid IPv6 address");
}

Validate IP Addresses:

// Check if string is valid IP
if (is_valid_ipv4("192.168.1.1")) {
    log_info("Valid IPv4");
}
 
if (is_valid_ipv6("2001:db8::1")) {
    log_info("Valid IPv6");
}

Format IP Addresses:

char ip_str[INET6_ADDRSTRLEN];
format_ip_address(&addr, ip_str, sizeof(ip_str));
log_info("IP: %s", ip_str);

UTF-8 String Handling

Validate UTF-8:

const char *text = "Hello, 世界!";
if (is_valid_utf8(text)) {
    log_info("Valid UTF-8 string");
}

Count UTF-8 Characters:

size_t char_count = utf8_strlen(text);
size_t byte_count = strlen(text);
log_info("Characters: %zu, Bytes: %zu", char_count, byte_count);

Iterate UTF-8 Characters:

const char *p = text;
while (*p) {
    uint32_t codepoint;
    size_t bytes = utf8_decode(p, &codepoint);
    log_debug("Codepoint: U+%04X", codepoint);
    p += bytes;
}

Path Utilities

Normalize Paths:

char normalized[PATH_MAX];
normalize_path("/path/to/../file.txt", normalized, sizeof(normalized));
// Result: "/path/file.txt"

Join Paths:

char joined[PATH_MAX];
join_path("/home/user", ".ssh/id_ed25519", joined, sizeof(joined));
// Result: "/home/user/.ssh/id_ed25519"

Expand Home Directory:

char expanded[PATH_MAX];
expand_home_dir("~/.ssh/known_hosts", expanded, sizeof(expanded));
// Result: "/home/username/.ssh/known_hosts"

Get File Extension:

const char *ext = get_file_extension("document.pdf");

// Result: "pdf"

String Utilities

Trim Whitespace:

char text[] = "  hello world  ";
trim_whitespace(text);
// Result: "hello world"

String Matching:

if (str_starts_with(text, "hello")) {
    log_info("Text starts with 'hello'");
}
 
if (str_ends_with(text, "world")) {
    log_info("Text ends with 'world'");
}

Case-Insensitive Compare:

if (strcasecmp_safe(str1, str2) == 0) {
    log_info("Strings are equal (case-insensitive)");
}

Parsing Utilities

Parse Integers:

int value;
if (parse_int("1234", &value)) {
    log_info("Parsed: %d", value);
}
 
// Parse with range validation
if (parse_int_range("42", &value, 0, 100)) {
    log_info("Valid value in range: %d", value);
}

Parse Floating Point:

double value;
if (parse_double("3.14159", &value)) {
    log_info("Parsed: %f", value);
}

Parse Boolean:

bool value;
if (parse_bool("true", &value)) {
    log_info("Boolean: %s", value ? "true" : "false");
}
// Accepts: "true", "false", "yes", "no", "1", "0" (case-insensitive)

Format Utilities

Format Byte Sizes:

char size_str[32];
format_bytes(1024 * 1024 * 5, size_str, sizeof(size_str));
// Result: "5.00 MB"

Format Duration:

char duration[64];
format_duration(3665, duration, sizeof(duration));
// Result: "1h 1m 5s"

Format Timestamp:

char timestamp[32];
format_timestamp(time(NULL), timestamp, sizeof(timestamp));
// Result: "2025-01-15 14:23:45"

Mathematical Utilities

Safe Integer Math:

// Clamp value to range
int clamped = clamp(value, 0, 100);
 
// Get minimum/maximum
int min_val = min(a, b);
int max_val = max(a, b);

Rounding:

// Round to nearest integer
int rounded = round_to_int(3.7);  // Result: 4
 
// Round up/down
int ceil_val = round_up(3.2);     // Result: 4
int floor_val = round_down(3.8);  // Result: 3

Alignment:

// Align to power of 2
size_t aligned = align_up(123, 16);    // Result: 128
size_t aligned_down = align_down(123, 16); // Result: 112

Performance Notes

CRC32 Hardware Acceleration:

~10x faster on x86 with SSE4.2
~8x faster on ARM with CRC32 instructions
Automatically detected at runtime

UTF-8 Validation:

Optimized for ASCII-common case
SIMD acceleration where available
Early exit on invalid sequences

Path Operations:

In-place modifications where possible
Minimal allocations
Platform-specific optimizations

Best Practices

DO:

Validate input strings before processing
Use UTF-8 functions for international text
Check return values from parsing functions
Use hardware-accelerated CRC32 when available
Normalize paths before comparison

DON'T:

Don't assume ASCII-only input
Don't ignore parse errors
Don't use strcpy/sprintf (use safe versions)
Don't hard-code path separators
Don't perform string operations without bounds checking

See also: lib/crc32.h; lib/util/aspect_ratio.h; lib/util/ip.h; lib/util/utf8.h; lib/util/path.h; lib/util/string.h; lib/util/parsing.h; lib/util/format.h; lib/util/math.h

Macro Definition Documentation

◆ asciichat_crc32

#define asciichat_crc32	(	data,
		len
	)	asciichat_crc32_hw((data), (len))

#include <crc32.h>

Main CRC32 dispatcher macro - use this in application code.

Parameters

data	Data to compute checksum for
len	Length of data in bytes

Returns: CRC32 checksum value (32-bit unsigned integer)

Recommended macro for CRC32 computation. Automatically dispatches to hardware-accelerated implementation when available, otherwise uses software fallback.

Note: This macro expands to asciichat_crc32_hw() which performs automatic hardware detection and fallback.; Use this macro in all application code for optimal performance with automatic hardware acceleration.

Example:: uint32_t checksum = asciichat_crc32(packet_data, packet_size);

asciichat_crc32
#define asciichat_crc32(data, len)
Main CRC32 dispatcher macro - use this in application code.
Definition crc32.h:144

Definition at line 144 of file crc32.h.

◆ FNV1A_32_HASH

#define FNV1A_32_HASH	(	hash,
		byte
	)

#include <fnv1a.h>

Value:

  do {                                                                                                                 \
    (hash) = (((hash) ^ (uint64_t)(byte)) * FNV1A_32_PRIME) & FNV1A_32_MASK;                                           \
  } while (0)

FNV-1a 32-bit hash macro for a single byte.

Definition at line 51 of file fnv1a.h.

     {                                                                                                                 \
    (hash) = (((hash) ^ (uint64_t)(byte)) * FNV1A_32_PRIME) & FNV1A_32_MASK;                                           \
  } while (0)

◆ FNV1A_32_MASK

#define FNV1A_32_MASK 0xFFFFFFFFULL

#include <fnv1a.h>

FNV-1a 32-bit mask.

Definition at line 41 of file fnv1a.h.

◆ FNV1A_32_OFFSET_BASIS

#define FNV1A_32_OFFSET_BASIS 2166136261ULL

#include <fnv1a.h>

FNV-1a 32-bit offset basis.

Definition at line 35 of file fnv1a.h.

◆ FNV1A_32_PRIME

#define FNV1A_32_PRIME 16777619ULL

#include <fnv1a.h>

FNV-1a 32-bit prime.

Definition at line 38 of file fnv1a.h.

◆ FNV1A_INIT

#define FNV1A_INIT ( hash ) uint64_t hash = FNV1A_32_OFFSET_BASIS;

#include <fnv1a.h>

FNV-1a 32-bit hash macro.

Definition at line 48 of file fnv1a.h.

◆ MAX_PATH_BASES

#define MAX_PATH_BASES 16

#include <path.h>

Maximum number of path base directories.

Maximum number of base directories that can be checked in path validation.

Definition at line 85 of file path.h.

◆ PASSWORD_MAX_LEN

#define PASSWORD_MAX_LEN 260

#include <password.h>

Buffer size for password input.

Passwords are limited to 256 characters per validate_opt_password(). Adding space for null terminator and some margin.

Definition at line 30 of file password.h.

◆ PATH_COMPONENT_DOT

#define PATH_COMPONENT_DOT '.'

#include <path.h>

Path component: current directory (single dot)

Character constant for the current directory component in paths.

Definition at line 59 of file path.h.

◆ PATH_COMPONENT_DOTDOT

#define PATH_COMPONENT_DOTDOT ".."

#include <path.h>

Path component: parent directory (double dot)

String constant for the parent directory component in paths.

Definition at line 66 of file path.h.

◆ PATH_DRIVE_SEPARATOR

#define PATH_DRIVE_SEPARATOR ':'

#include <path.h>

Path component: Windows drive separator (colon)

Definition at line 78 of file path.h.

◆ PATH_TILDE

#define PATH_TILDE '~'

#include <path.h>

Path component: home directory tilde.

The home directory component in paths (e.g., "~/path").

Definition at line 73 of file path.h.

◆ ROUND

#define ROUND ( xfloat ) (int)(0.5f + (xfloat))

#include <math.h>

Round floating-point value to nearest integer.

Parameters

xfloat Floating-point value to round

Returns: Nearest integer value

Rounds a floating-point value to the nearest integer using standard rounding rules (0.5 rounds up). Uses simple addition of 0.5 and truncation.

Note: This is a macro for performance (inlined at compile time).; Uses standard rounding (banker's rounding not applied).

Example: int rounded = ROUND(3.7); // Returns 4

int rounded = ROUND(3.2); // Returns 3

int rounded = ROUND(-2.5); // Returns -2

ROUND
#define ROUND(xfloat)
Round floating-point value to nearest integer.
Definition math.h:53

Definition at line 53 of file math.h.

◆ SIZE_ADD_SAFE

#define SIZE_ADD_SAFE	(	a,
		b
	)	(size_add_would_overflow(a, b) ? SIZE_MAX : (a) + (b))

#include <overflow.h>

Add with overflow check inline (macro form for tight loops)

Parameters

a	First operand
b	Second operand

Returns: Sum if no overflow, SIZE_MAX if would overflow

Macro version of checked addition that returns SIZE_MAX on overflow.

Warning: The result SIZE_MAX might be a valid sum. Use the function version (checked_size_add) for proper error handling in most code.

Definition at line 244 of file overflow.h.

◆ SIZE_MUL_SAFE

#define SIZE_MUL_SAFE	(	a,
		b
	)	(size_mul_would_overflow(a, b) ? SIZE_MAX : (a) * (b))

#include <overflow.h>

Multiply with overflow check inline (macro form for tight loops)

Parameters

a	First operand
b	Second operand

Returns: Product if no overflow, SIZE_MAX if would overflow

Macro version of checked multiplication that returns SIZE_MAX on overflow. Useful in performance-critical loops where you want to avoid function calls.

Warning: The result SIZE_MAX might be a valid product. Use the function version (checked_size_mul) for proper error handling in most code.

Definition at line 229 of file overflow.h.

Enumeration Type Documentation

◆ path_role_t

enum path_role_t

#include <path.h>

Classification for user-supplied filesystem paths.

Enumerator
PATH_ROLE_CONFIG_FILE	Configuration files such as config.toml
PATH_ROLE_LOG_FILE	Log file destinations
PATH_ROLE_KEY_PRIVATE	Private key files (SSH/GPG)
PATH_ROLE_KEY_PUBLIC	Public key files or expected server keys
PATH_ROLE_CLIENT_KEYS	Client key whitelist files

Definition at line 316 of file path.h.

             {
  PATH_ROLE_CONFIG_FILE, 
  PATH_ROLE_LOG_FILE,    
  PATH_ROLE_KEY_PRIVATE, 
  PATH_ROLE_KEY_PUBLIC,  
  PATH_ROLE_CLIENT_KEYS  
} path_role_t;

Function Documentation

◆ __isoc23_scanf()

int __isoc23_scanf	(	const char *	format,
			...
	)

#include <musl_c23_compat.c>

Formatted input functions.

Read formatted input from stdin (C23 compatible)

Parameters

format	Format string
...	Variable arguments

Returns: Number of successfully read items

Definition at line 114 of file musl_c23_compat.c.

                                            {
  va_list args;
  va_start(args, format);
  int result = vscanf(format, args);
  va_end(args);
  return result;
}

References args.

◆ __isoc23_wcstol()

long __isoc23_wcstol	(	const wchar_t *	str,
		wchar_t **	endptr,
		int	base
	)

#include <musl_c23_compat.c>

Wide string to integer conversion.

Convert wide string to long (C23 compatible)

Parameters

str	Wide string to convert
endptr	Pointer to first non-digit character (optional)
base	Numeric base (0-36)

Returns: Converted value

Definition at line 67 of file musl_c23_compat.c.

                                                                     {
  return wcstol(str, endptr, base);
}

◆ __isoc23_wscanf()

int __isoc23_wscanf	(	const wchar_t *	format,
			...
	)

#include <musl_c23_compat.c>

Wide character formatted input functions.

Read formatted wide input from stdin (C23 compatible)

Parameters

format	Format string
...	Variable arguments

Returns: Number of successfully read items

Definition at line 194 of file musl_c23_compat.c.

                                                {
  va_list args;
  va_start(args, format);
  int result = vwscanf(format, args);
  va_end(args);
  return result;
}

References args.

◆ arc4random_buf()

void arc4random_buf	(	void *	buf,
		size_t	nbytes
	)

#include <musl_c23_compat.c>

glibc-specific random functions for expat and fontconfig compatibility

Fill buffer with cryptographically secure random bytes

Used by expat for hash seeding and other security-critical operations. Attempts getrandom syscall first (Linux 3.17+), falls back to /dev/urandom.

Parameters

buf	Output buffer (must not be NULL if nbytes > 0)
nbytes	Number of random bytes to generate

Definition at line 283 of file musl_c23_compat.c.

                                              {
  if (nbytes == 0 || buf == NULL) {
    return;
  }
 
/* Prefer getrandom syscall: available in Linux 3.17+, no file descriptor needed */
#ifdef SYS_getrandom
  long result = syscall(SYS_getrandom, buf, nbytes, 0);
  if (result == (long)nbytes) {
    return;
  }
#endif
 
  /* Fallback to /dev/urandom device */
  int fd = open("/dev/urandom", O_RDONLY);
  if (fd >= 0) {
    ssize_t n = read(fd, buf, nbytes);
    close(fd);
    if (n == (ssize_t)nbytes) {
      return;
    }
  }
 
  /* Fatal error: unable to obtain random bytes */
  abort();
}

Referenced by random_r().

◆ asciichat_crc32_hw()

uint32_t asciichat_crc32_hw	(	const void *	data,
		size_t	len
	)

#include <crc32.h>

Compute CRC32 checksum with hardware acceleration (if available)

Parameters

data	Data to compute checksum for (must not be NULL)
len	Length of data in bytes

Returns: CRC32 checksum value (32-bit unsigned integer)

Computes CRC32 checksum using hardware acceleration when available. Automatically falls back to software implementation if hardware is not available on the current platform.

Note

This function performs runtime CPU feature detection to determine whether to use hardware or software implementation.

Hardware acceleration is available on:

x86/x64 processors with SSE4.2 (CRC32 instruction)
ARM processors with ARMv8 (CRC32 instructions)

For consistent performance testing or when hardware detection is not desired, use asciichat_crc32_sw() directly.

The CRC32 polynomial used is IEEE 802.3 (CRC-32), which is compatible with standard CRC32 implementations.

Definition at line 132 of file crc32.c.

                                                          {
  check_crc32_hw_support();
 
  if (!crc32_hw_available) {
    // DEBUG: Log fallback to software
    static bool logged_fallback = false;
    if (!logged_fallback) {
      log_debug("Using software CRC32 (no hardware acceleration)");
      logged_fallback = true;
    }
    return asciichat_crc32_sw(data, len);
  }
 
#ifdef ARCH_ARM64
  static bool logged_arm = false;
  if (!logged_arm) {
    log_debug("Using ARM64 hardware CRC32");
    logged_arm = true;
  }
  return crc32_arm_hw(data, len);
#elif defined(ARCH_X86_64)
  static bool logged_intel = false;
  if (!logged_intel) {
    log_debug("Using Intel x86_64 hardware CRC32 (SSE4.2)");
    logged_intel = true;
  }
  return crc32_intel_hw(data, len);
#else
  return asciichat_crc32_sw(data, len);
#endif
}

References asciichat_crc32_sw(), and log_debug.

◆ asciichat_crc32_sw()

uint32_t asciichat_crc32_sw	(	const void *	data,
		size_t	len
	)

#include <crc32.h>

Compute CRC32 checksum using software implementation only.

Parameters

data	Data to compute checksum for (must not be NULL)
len	Length of data in bytes

Returns: CRC32 checksum value (32-bit unsigned integer)

Computes CRC32 checksum using a software lookup table implementation. Always uses software implementation regardless of hardware availability.

Note: This function provides consistent performance across all platforms, which is useful for testing and benchmarking.; For production code, prefer asciichat_crc32() macro which automatically uses hardware acceleration when available.; The CRC32 polynomial used is IEEE 802.3 (CRC-32), which is compatible with standard CRC32 implementations.

Definition at line 171 of file crc32.c.

                                                          {
  const uint8_t *bytes = (const uint8_t *)data;
  uint32_t crc = 0xFFFFFFFF;
 
  // CRC32-C (Castagnoli) polynomial: 0x1EDC6F41
  // Reversed (for LSB-first): 0x82F63B78
  for (size_t i = 0; i < len; i++) {
    crc ^= bytes[i];
    for (int j = 0; j < 8; j++) {
      if (crc & 1) {
        crc = (crc >> 1) ^ 0x82F63B78; // CRC32-C polynomial (reversed)
      } else {
        crc >>= 1;
      }
    }
  }
 
  return ~crc;
}

Referenced by asciichat_crc32_hw(), client_parse_packet(), and client_serialize_packet().

◆ aspect_ratio()

void aspect_ratio	(	const ssize_t	img_width,
		const ssize_t	img_height,
		const ssize_t	width,
		const ssize_t	height,
		const bool	stretch,
		ssize_t *	out_width,
		ssize_t *	out_height
	)

#include <aspect_ratio.h>

Calculate aspect ratio with terminal character correction.

Parameters

img_width	Input image width in pixels (must be > 0)
img_height	Input image height in pixels (must be > 0)
width	Target width in terminal characters (must be > 0)
height	Target height in terminal lines (must be > 0)
stretch	Whether to allow stretching (true) or maintain aspect ratio (false)
out_width	Output parameter for calculated width (must not be NULL)
out_height	Output parameter for calculated height (must not be NULL)

Calculates output dimensions for ASCII art rendering with terminal character aspect ratio correction. Terminal characters are typically taller than wide (e.g., 2:1 ratio), so this function corrects for that to maintain proper image proportions in ASCII art.

TERMINAL CORRECTION:

Applies character aspect ratio correction (accounts for terminal font)
Ensures ASCII art matches original image proportions
When stretch=false, maintains original image aspect ratio
When stretch=true, fills target dimensions exactly

Note: Output dimensions respect target size while maintaining aspect ratio.; Terminal character correction is essential for proper ASCII art rendering.; Output parameters are modified to contain calculated dimensions.

Example: ssize_t out_w, out_h;

aspect_ratio(1920, 1080, 80, 40, false, &out_w, &out_h);

// Calculates dimensions that fit within 80x40 terminal while maintaining 16:9 aspect

aspect_ratio
void aspect_ratio(const ssize_t img_w, const ssize_t img_h, const ssize_t width, const ssize_t height, const bool stretch, ssize_t *out_width, ssize_t *out_height)
Calculate aspect ratio with terminal character correction.
Definition aspect_ratio.c:69

Definition at line 69 of file aspect_ratio.c.

                                                                               {
  // Input validation
  if (!out_width || !out_height) {
    return; // or log error
  }
 
  if (img_w <= 0 || img_h <= 0) {
    // Handle degenerate image dimensions
    *out_width = MIN_DIMENSION;
    *out_height = MIN_DIMENSION;
    return;
  }
 
  if (stretch) {
    // If stretching is enabled, just use the full terminal dimensions
    *out_width = width;
    *out_height = height;
  } else {
    // Calculate aspect-correct dimensions to fit within the given width/height
    calculate_fit_dimensions(img_w, img_h, width, height, out_width, out_height);
  }
}

References MIN_DIMENSION.

Referenced by ascii_convert().

◆ aspect_ratio2()

void aspect_ratio2	(	const ssize_t	img_width,
		const ssize_t	img_height,
		const ssize_t	target_width,
		const ssize_t	target_height,
		ssize_t *	out_width,
		ssize_t *	out_height
	)

#include <aspect_ratio.h>

Simple aspect ratio calculation without terminal character correction.

Parameters

img_width	Input image width in pixels (must be > 0)
img_height	Input image height in pixels (must be > 0)
target_width	Target width (must be > 0)
target_height	Target height (must be > 0)
out_width	Output parameter for calculated width (must not be NULL)
out_height	Output parameter for calculated height (must not be NULL)

Calculates output dimensions that maintain the input image's aspect ratio while fitting within target dimensions. This is a simple pixel-based calculation without terminal character correction.

Note: This function does NOT apply terminal character correction.; Use aspect_ratio() for ASCII art rendering (with terminal correction).; Output dimensions are calculated to fit within target while maintaining ratio.

Example: ssize_t out_w, out_h;

aspect_ratio2(1920, 1080, 800, 600, &out_w, &out_h);

// Calculates dimensions that fit within 800x600 while maintaining 16:9 aspect

aspect_ratio2
void aspect_ratio2(const ssize_t img_w, const ssize_t img_h, const ssize_t target_w, const ssize_t target_h, ssize_t *out_width, ssize_t *out_height)
Simple aspect ratio calculation without terminal character correction.
Definition aspect_ratio.c:95

Definition at line 95 of file aspect_ratio.c.

                                                            {
  // Input validation
  if (!out_width || !out_height) {
    return;
  }
 
  if (img_w <= 0 || img_h <= 0 || target_w <= 0 || target_h <= 0) {
    // Handle invalid dimensions
    *out_width = MIN_DIMENSION;
    *out_height = MIN_DIMENSION;
    return;
  }
 
  // Calculate aspect ratio
  float img_aspect = (float)img_w / (float)img_h;
 
  // We want the image to fill at least one dimension of the target box
  // while maintaining aspect ratio and fitting within the box
 
  // Calculate dimensions if we scale to fill width
  ssize_t width_if_fill_width = target_w;
  ssize_t height_if_fill_width = (ssize_t)((float)target_w / img_aspect);
 
  // Calculate dimensions if we scale to fill height
  ssize_t width_if_fill_height = (ssize_t)((float)target_h * img_aspect);
  ssize_t height_if_fill_height = target_h;
 
  // Choose the scaling that maximizes usage of the target box
  // We want to fill at least one dimension completely
  if (height_if_fill_width <= target_h) {
    // Filling width fits within height - use it
    *out_width = width_if_fill_width;
    *out_height = height_if_fill_width;
  } else {
    // Filling width would exceed height, so fill height instead
    *out_width = width_if_fill_height;
    *out_height = height_if_fill_height;
  }
 
  // Ensure minimum dimensions
  if (*out_width <= 0) {
    *out_width = MIN_DIMENSION;
  }
  if (*out_height <= 0) {
    *out_height = MIN_DIMENSION;
  }
}

References MIN_DIMENSION.

◆ calculate_fit_dimensions_pixel()

void calculate_fit_dimensions_pixel	(	int	img_width,
		int	img_height,
		int	max_width,
		int	max_height,
		int *	out_width,
		int *	out_height
	)

#include <aspect_ratio.h>

Calculate fit dimensions for pixel-based images.

Parameters

img_width	Input image width in pixels (must be > 0)
img_height	Input image height in pixels (must be > 0)
max_width	Maximum allowed width in pixels (must be > 0)
max_height	Maximum allowed height in pixels (must be > 0)
out_width	Output parameter for calculated width (must not be NULL)
out_height	Output parameter for calculated height (must not be NULL)

Calculates dimensions that fit the input image within maximum bounds while maintaining the original aspect ratio. Useful for scaling images to fit within display constraints.

Note: Output dimensions never exceed max_width or max_height.; Aspect ratio is always maintained (image is not stretched).; Output dimensions are calculated to fit within maximum bounds.

Example: int out_w, out_h;

calculate_fit_dimensions_pixel(1920, 1080, 1280, 720, &out_w, &out_h);

// Calculates dimensions that fit within 1280x720 while maintaining 16:9 aspect

// Result: out_w=1280, out_h=720 (fits exactly)

calculate_fit_dimensions_pixel
void calculate_fit_dimensions_pixel(int img_width, int img_height, int max_width, int max_height, int *out_width, int *out_height)
Calculate fit dimensions for pixel-based images.
Definition aspect_ratio.c:146

Definition at line 146 of file aspect_ratio.c.

                                                     {
  if (!out_width || !out_height || img_width <= 0 || img_height <= 0) {
    if (out_width)
      *out_width = max_width;
    if (out_height)
      *out_height = max_height;
    return;
  }
 
  float src_aspect = (float)img_width / (float)img_height;
 
  // Try filling width
  int width_if_fill_w = max_width;
  int height_if_fill_w = (int)(((float)max_width / src_aspect) + 0.5f);
 
  // Try filling height
  int width_if_fill_h = (int)(((float)max_height * src_aspect) + 0.5f);
  int height_if_fill_h = max_height;
 
  // log_debug("calculate_fit_dimensions: img %dx%d (aspect %.3f), max %dx%d", img_width, img_height, src_aspect,
  //           max_width, max_height);
  // log_debug("  Fill width: %dx%d, Fill height: %dx%d", width_if_fill_w, height_if_fill_w, width_if_fill_h,
  //           height_if_fill_h);
 
  // Choose the option that fits
  if (height_if_fill_w <= max_height) {
    // Filling width fits
    // log_debug("  Choosing fill width: %dx%d", width_if_fill_w, height_if_fill_w);
    *out_width = width_if_fill_w;
    *out_height = height_if_fill_w;
  } else {
    // Fill height instead
    // log_debug("  Choosing fill height: %dx%d", width_if_fill_h, height_if_fill_h);
    *out_width = width_if_fill_h;
    *out_height = height_if_fill_h;
  }
 
  // Clamp to bounds
  if (*out_width > max_width)
    *out_width = max_width;
  if (*out_height > max_height)
    *out_height = max_height;
  if (*out_width < 1)
    *out_width = 1;
  if (*out_height < 1)
    *out_height = 1;
 
  // log_debug("  Final output: %dx%d", *out_width, *out_height);
}

◆ canonicalize_ipv6()

asciichat_error_t canonicalize_ipv6	(	const char *	ipv6,
		char *	canonical_out,
		size_t	out_size
	)

#include <ip.h>

Canonicalize IPv6 address to standard form.

Parameters

ipv6	IPv6 address (must not be NULL)
canonical_out	Output buffer for canonical form (must not be NULL)
out_size	Size of output buffer

Returns: ASCIICHAT_OK on success, error code on failure

Converts an IPv6 address to canonical form following RFC 5952:

Lowercase hexadecimal digits
Leading zeros removed from each group
Longest run of consecutive zero groups compressed to ::
Brackets removed

EXAMPLES:

"2001:0DB8:0000:0000:0000:0000:0000:0001" -> "2001:db8::1"
"[::1]" -> "::1"
"2001:DB8::1" -> "2001:db8::1"

Note: Output buffer should be at least 64 bytes.; Returns error if input is not a valid IPv6 address.

Example: char canonical[64];

if (canonicalize_ipv6("[2001:0DB8::1]", canonical, sizeof(canonical)) == ASCIICHAT_OK) {

// canonical = "2001:db8::1"

}

ASCIICHAT_OK
@ ASCIICHAT_OK
Definition error_codes.h:51

canonicalize_ipv6
asciichat_error_t canonicalize_ipv6(const char *ipv6, char *canonical_out, size_t out_size)
Canonicalize IPv6 address to standard form.
Definition ip.c:969

Definition at line 969 of file ip.c.

                                                                                            {
  if (!ipv6 || !canonical_out || out_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments to canonicalize_ipv6");
  }
 
  // Normalize (remove brackets)
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ipv6, normalized, sizeof(normalized)) != 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Failed to parse IPv6 address");
  }
 
  // Validate
  if (!is_valid_ipv6(normalized)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IPv6 address: %s", ipv6);
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Failed to convert IPv6 address");
  }
 
  // Use inet_ntop which produces canonical form
  if (inet_ntop(AF_INET6, &addr, canonical_out, (socklen_t)out_size) == NULL) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to format IPv6 address");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, is_valid_ipv6(), parse_ipv6_address(), and SET_ERRNO.

Referenced by compact_ipv6(), and compare_ip_port_strings().

◆ colored_string()

const char * colored_string	(	log_color_t	color,
		const char *	text
	)

#include <string.h>

Build a colored string for terminal output.

Wraps text with ANSI color codes based on terminal capabilities. Uses a rotating buffer to handle multiple colored strings in the same scope. Checks if stdout is a TTY and CLAUDECODE environment variable.

BEHAVIOR:

If stdout is a TTY and CLAUDECODE is not set: Returns colored text with ANSI codes
If stdout is not a TTY or CLAUDECODE is set: Returns plain text without colors
Detects terminal color capabilities (respects NO_COLOR and terminal restrictions)

USAGE:

// Single colored string
fprintf(stderr, "%s\n", colored_string(LOG_COLOR_FATAL, "Error"));
 
// Multiple colored strings in same scope (uses rotating buffers)
fprintf(stderr, "%s %s\n",
        colored_string(LOG_COLOR_FATAL, "Error:"),
        colored_string(LOG_COLOR_WARN, "warning message"));

Parameters

color	The log color to apply (LOG_COLOR_DEBUG, LOG_COLOR_FATAL, LOG_COLOR_WARN, etc.)
text	The text to color

Returns: Colored string with ANSI codes, or plain text if colors disabled

Note: The returned pointer points to a static rotating buffer. Use or copy the result before calling colored_string() again in tight loops.; Color codes are applied based on log_level_color() from logging subsystem.

Definition at line 274 of file util/string.c.

                                                                {
#define COLORED_BUFFERS 4
#define COLORED_BUFFER_SIZE 256
  static char buffers[COLORED_BUFFERS][COLORED_BUFFER_SIZE];
  static int buffer_idx = 0;
 
  if (!text) {
    return "";
  }
 
  // Check if we should use colors
  // Use global flag that persists even after options cleanup
  bool use_colors = false;
 
  // Priority 1: If --color was explicitly passed, force colors
  if (g_color_flag_passed && g_color_flag_value) {
    use_colors = true;
  }
  // Priority 2: If --color NOT explicitly passed, use terminal detection
  else if (!g_color_flag_passed) {
    use_colors = terminal_should_color_output(STDOUT_FILENO);
  }
  // Priority 3: If --color=false was explicitly passed, disable colors
  // (use_colors stays false)
 
  if (!use_colors) {
    // No colors, just return the text directly
    return text;
  }
 
  // Use rotating buffer to handle multiple calls in same fprintf
  char *current_buf = buffers[buffer_idx];
  buffer_idx = (buffer_idx + 1) % COLORED_BUFFERS;
 
  const char *color_code = log_level_color(color);
  const char *reset_code = log_level_color(LOG_COLOR_RESET);
 
  // Ensure we never pass NULL to snprintf (handle uninitialized color system)
  if (!color_code)
    color_code = "";
  if (!reset_code)
    reset_code = "";
 
  // Format into rotating static buffer: color_code + text + reset_code
  safe_snprintf(current_buf, COLORED_BUFFER_SIZE, "%s%s%s", color_code, text, reset_code);
  return current_buf;
}

References COLORED_BUFFER_SIZE, COLORED_BUFFERS, g_color_flag_passed, g_color_flag_value, LOG_COLOR_RESET, log_level_color(), safe_snprintf(), and terminal_should_color_output().

Referenced by action_show_capabilities_immediate(), action_show_version(), asciichat_print_error_context(), backtrace_print(), colorize_log_message(), colorize_named_string(), log_labeled(), log_template_apply(), mutex_stack_detect_deadlocks(), options_config_calculate_max_col_width(), options_config_print_options_sections_with_width(), options_config_print_usage(), options_print_help_for_mode(), platform_is_binary_in_path(), print_project_links(), and ui_mdns_select().

◆ compact_ipv6()

asciichat_error_t compact_ipv6	(	const char *	ipv6,
		char *	compact_out,
		size_t	out_size
	)

#include <ip.h>

Compress IPv6 address using :: notation.

Parameters

ipv6	IPv6 address (must not be NULL)
compact_out	Output buffer for compressed form (must not be NULL)
out_size	Size of output buffer

Returns: ASCIICHAT_OK on success, error code on failure

Compresses an IPv6 address by replacing the longest run of consecutive zero groups with ::. Follows RFC 5952 compression rules.

EXAMPLES:

"2001:0db8:0000:0000:0000:0000:0000:0001" -> "2001:db8::1"
"fe80:0000:0000:0000:0000:0000:0000:0001" -> "fe80::1"
"2001:db8:0:0:1:0:0:1" -> "2001:db8::1:0:0:1"

Note: Output buffer should be at least 64 bytes.; Returns error if input is not a valid IPv6 address.; Alias for canonicalize_ipv6() - both produce the same output.

Example: char compact[64];

if (compact_ipv6("2001:0db8:0000:0000:0000:0000:0000:0001", compact, sizeof(compact)) == ASCIICHAT_OK) {

// compact = "2001:db8::1"

}

compact_ipv6
asciichat_error_t compact_ipv6(const char *ipv6, char *compact_out, size_t out_size)
Compress IPv6 address using :: notation.
Definition ip.c:999

Definition at line 999 of file ip.c.

                                                                                     {
  return canonicalize_ipv6(ipv6, compact_out, out_size);
}

References canonicalize_ipv6().

◆ compare_ip_port_strings()

int compare_ip_port_strings	(	const char *	ip_port1,
		const char *	ip_port2
	)

#include <ip.h>

Compare two "IP:port" strings with IPv6 normalization.

Compares two formatted address strings (e.g., "192.168.1.1:8080" or "[::1]:8080") with proper handling of different IPv6 representations.

Handles IPv6 normalization so different representations are treated as equal:

"[::1]:8080" equals "[0:0:0:0:0:0:0:1]:8080"
"[2001:db8::1]:80" equals "[2001:0db8:0000:0000:0000:0000:0000:0001]:80"

For IPv4 addresses, uses robust comparison via ip_equals() that handles different binary representations correctly.

Parameters

ip_port1	First "IP:port" string (IPv4: "192.168.1.1:8080", IPv6: "[::1]:8080")
ip_port2	Second "IP:port" string to compare

Returns: 1 if addresses match (after normalization), 0 otherwise

Example: // IPv6 normalization

int match1 = compare_ip_port_strings("[::1]:8080", "[0:0:0:0:0:0:0:1]:8080");

// Returns 1 (equal after normalization)

// IPv4 comparison

int match2 = compare_ip_port_strings("192.168.1.1:80", "192.168.1.1:80");

// Returns 1 (equal)

// Different ports

int match3 = compare_ip_port_strings("192.168.1.1:80", "192.168.1.1:8080");

// Returns 0 (different ports)

compare_ip_port_strings
int compare_ip_port_strings(const char *ip_port1, const char *ip_port2)
Compare two "IP:port" strings with IPv6 normalization.
Definition ip.c:1133

Definition at line 1133 of file ip.c.

                                                                        {
  if (!ip_port1 || !ip_port2) {
    return 0; // Not equal
  }
 
  // Fast path: if strings are identical, no parsing needed
  if (strcmp(ip_port1, ip_port2) == 0) {
    return 1; // Equal
  }
 
  // Parse both IP:port strings
  char ip1[64], ip2[64];
  uint16_t port1 = 0, port2 = 0;
 
  if (parse_ip_with_port(ip_port1, ip1, sizeof(ip1), &port1) != 0) {
    return 0; // Invalid format - not equal
  }
  if (parse_ip_with_port(ip_port2, ip2, sizeof(ip2), &port2) != 0) {
    return 0; // Invalid format - not equal
  }
 
  // Ports must match exactly
  if (port1 != port2) {
    return 0; // Not equal
  }
 
  // For IPv6, normalize both addresses before comparison
  int version1 = get_ip_version(ip1);
  int version2 = get_ip_version(ip2);
 
  // IP versions must match
  if (version1 != version2 || version1 == 0) {
    return 0; // Not equal
  }
 
  if (version1 == 6) {
    // Normalize both IPv6 addresses
    char canonical1[INET6_ADDRSTRLEN], canonical2[INET6_ADDRSTRLEN];
    if (canonicalize_ipv6(ip1, canonical1, sizeof(canonical1)) != ASCIICHAT_OK) {
      return 0; // Failed to normalize - not equal
    }
    if (canonicalize_ipv6(ip2, canonical2, sizeof(canonical2)) != ASCIICHAT_OK) {
      return 0; // Failed to normalize - not equal
    }
    return (strcmp(canonical1, canonical2) == 0) ? 1 : 0;
  } else {
    // IPv4: use ip_equals for robust comparison
    return ip_equals(ip1, ip2) ? 1 : 0;
  }
}

References ASCIICHAT_OK, canonicalize_ipv6(), get_ip_version(), ip_equals(), and parse_ip_with_port().

Referenced by check_known_host(), and check_known_host_no_identity().

◆ crc32_hw_is_available()

bool crc32_hw_is_available ( void )

#include <crc32.h>

Check if hardware CRC32 acceleration is available at runtime.

Returns: true if hardware acceleration is available, false otherwise

Performs runtime CPU feature detection to determine if hardware CRC32 acceleration can be used on the current platform.

Note

Detection is performed once per program execution and cached. Subsequent calls return the cached result.

Hardware acceleration is available on:

x86/x64: Processors with SSE4.2 feature (CRC32 instruction)
ARM: Processors with ARMv8 architecture (CRC32 instructions)

Use this function to determine if hardware acceleration will be used before calling asciichat_crc32_hw().

Definition at line 164 of file crc32.c.

                                 {
  check_crc32_hw_support();
  return crc32_hw_available;
}

◆ display_center_horizontal()

int display_center_horizontal	(	const char *	text,
		int	terminal_width
	)

#include <display.h>

Calculate left padding needed to center text horizontally.

Calculates how many spaces are needed before text to center it within a given terminal width. Properly handles ANSI escape codes and UTF-8.

Parameters

text	Text to center (may contain ANSI codes, must not be NULL)
terminal_width	Total width available for centering (e.g., 80)

Returns: Number of spaces to print before text, or 0 if text is wider than terminal

Example: // Center "Hello" in 80-char line

int padding = display_center_horizontal("\033[1;36mHello\033[0m", 80);

// Returns 38 ((80-5)/2 = 37.5, rounds to 38)

display_center_horizontal
int display_center_horizontal(const char *text, int terminal_width)
Calculate left padding needed to center text horizontally.
Definition lib/util/display.c:32

Definition at line 32 of file lib/util/display.c.

                                                                    {
  if (!text || terminal_width <= 0) {
    return 0;
  }
 
  int text_width = display_width(text);
 
  // If text is empty or wider than terminal, don't add padding
  if (text_width == 0 || text_width >= terminal_width) {
    return 0;
  }
 
  // Calculate left padding to center
  return (terminal_width - text_width) / 2;
}

References display_width().

◆ display_center_vertical()

int display_center_vertical	(	int	content_height,
		int	terminal_height
	)

#include <display.h>

Calculate top padding needed to vertically center content.

Calculates how many newlines are needed before content to center it vertically within a terminal of given height.

Parameters

content_height	Height of content in lines
terminal_height	Total height available (typical: 24-30 lines)

Returns: Number of newlines to print before content

Example: // Center 8-line status screen in 24-line terminal

int padding = display_center_vertical(8, 24);

// Returns 8 ((24-8)/2 = 8 lines)

display_center_vertical
int display_center_vertical(int content_height, int terminal_height)
Calculate top padding needed to vertically center content.
Definition lib/util/display.c:48

Definition at line 48 of file lib/util/display.c.

                                                                     {
  if (content_height <= 0 || terminal_height <= 0) {
    return 0;
  }
 
  if (content_height >= terminal_height) {
    return 0;
  }
 
  return (terminal_height - content_height) / 2;
}

◆ display_height()

int display_height	(	const char *	text,
		int	terminal_width
	)

#include <display.h>

Calculate how many display lines text will consume when wrapped.

Splits text by newlines and calculates how many terminal rows it will occupy when wrapped to the given terminal width. Properly handles ANSI escape codes (ignored in width calculation) and UTF-8 multi-byte characters.

Parameters

text	Input text which may contain ANSI codes and newlines (NULL-safe)
terminal_width	Width available for wrapping (e.g., 80)

Returns: Number of display lines consumed, or 0 if text is empty

Example: // "Hello\nWorld" in 80-char terminal = 2 lines

int height = display_height("Hello\nWorld", 80); // Returns 2

// "This is a very long line..." wrapped to 40 chars

int height = display_height("This is a very long line that exceeds...", 40);

// Returns 2-3 depending on exact length

// With ANSI codes: "\033[1;36m" is not counted in width

int height = display_height("\033[1;36m50-char line\033[0m", 40);

// Returns 2 (50 visible chars / 40 width)

Definition at line 60 of file lib/util/display.c.

                                                         {
  if (!text || terminal_width <= 0) {
    return 0;
  }
 
  int total_lines = 0;
  const char *p = text;
 
  // Count lines by processing the text and counting newlines + final segment
  while (*p) {
    // Find the end of this line (next newline or end of string)
    const char *line_end = p;
    while (*line_end && *line_end != '\n') {
      line_end++;
    }
 
    // Calculate display width of this line
    size_t line_len = line_end - p;
    if (line_len > 0) {
      // Strip ANSI codes and calculate display width
      char *stripped = ansi_strip_escapes(p, line_len);
      if (stripped) {
        int line_width = utf8_display_width(stripped);
        SAFE_FREE(stripped);
 
        if (line_width > 0) {
          // Calculate how many display lines this wraps to
          int display_lines = (line_width + terminal_width - 1) / terminal_width; // Ceiling division
          total_lines += display_lines;
        } else {
          total_lines += 1;
        }
      } else {
        // If stripping fails, count as 1 line
        total_lines += 1;
      }
    } else {
      // Empty line still counts as 1 line
      total_lines += 1;
    }
 
    // Move to next line
    if (*line_end == '\n') {
      p = line_end + 1;
    } else {
      break;
    }
  }
 
  return total_lines;
}

References ansi_strip_escapes(), SAFE_FREE, and utf8_display_width().

Referenced by terminal_screen_render().

◆ display_width()

int display_width ( const char * text )

#include <display.h>

Calculate the visible display width of text with ANSI escape codes.

Strips ANSI escape sequences and calculates the actual terminal display width. Properly handles UTF-8 multi-byte characters and wide characters.

Parameters

text	Input text which may contain ANSI escape codes (must not be NULL)

Returns: Display width in terminal columns, or -1 on error

Example: int width = display_width("\033[1;36mHello\033[0m"); // Returns 5

Definition at line 13 of file lib/util/display.c.

                                    {
  if (!text) {
    return 0;
  }
 
  // Strip ANSI escape codes
  char *stripped = ansi_strip_escapes(text, strlen(text));
 
  // Use stripped version if available, otherwise use original text
  const char *to_measure = stripped ? stripped : text;
 
  // Calculate display width using UTF-8 aware calculation
  int width = utf8_display_width(to_measure);
  SAFE_FREE(stripped);
 
  // Return 0 for empty or invalid input, otherwise return calculated width
  return width < 0 ? 0 : width;
}

References ansi_strip_escapes(), SAFE_FREE, and utf8_display_width().

Referenced by display_center_horizontal(), frame_buffer_render_centered(), layout_print_two_column_row(), terminal_fd_reader_next(), terminal_screen_render(), and truncate_with_ellipsis().

◆ escape_ascii()

void escape_ascii	(	const char *	str,
		const char *	escape_char,
		char *	out_buffer,
		size_t	out_buffer_size
	)

#include <string.h>

Escape ASCII characters in a string.

Parameters

str	Input string to escape (must not be NULL)
escape_char	Character to escape (must not be NULL)
out_buffer	Output buffer for escaped string (must not be NULL)
out_buffer_size	Size of output buffer (must be > 0)

Escapes a specific ASCII character in a string by adding an escape prefix. Useful for terminal output or string formatting where certain characters need to be escaped.

Note: Output buffer must be large enough to hold the escaped string.; Function truncates output if buffer is too small.; Does not validate input parameters for NULL (caller's responsibility).

Definition at line 20 of file util/string.c.

                                                                                                      {
  if (escape_char == NULL || str == NULL || !out_buffer || out_buffer_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid string or escape character or output buffer");
    return;
  }
 
  // Count how many characters need escaping
  size_t escape_count = 0;
  for (size_t i = 0; i < strlen(str); i++) {
    for (size_t j = 0; j < strlen(escape_char); j++) {
      if (str[i] == escape_char[j]) {
        escape_count++;
        break;
      }
    }
  }
 
  size_t total_len = strlen(str) + escape_count;
  if (out_buffer_size < total_len) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Output buffer is too small");
    return;
  }
 
  size_t out_pos = 0;
  for (size_t i = 0; i < strlen(str); i++) {
    bool needs_escape = false;
    for (size_t j = 0; j < strlen(escape_char); j++) {
      if (str[i] == escape_char[j]) {
        needs_escape = true;
        break;
      }
    }
 
    if (needs_escape) {
      out_buffer[out_pos++] = '\\';
    }
    out_buffer[out_pos++] = str[i];
  }
 
  out_buffer[out_pos] = '\0';
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by display_mitm_warning().

◆ escape_path_for_shell()

bool escape_path_for_shell	(	const char *	path,
		char *	out_buffer,
		size_t	out_buffer_size
	)

#include <string.h>

Escape a path for safe use in shell commands (auto-platform)

Parameters

path	Path string to escape (must not be NULL)
out_buffer	Output buffer for escaped path (must not be NULL)
out_buffer_size	Size of output buffer (must be > 0)

Returns: true on success, false on failure

Automatically escapes a path for safe use in shell commands. If the path contains special characters or whitespace, it applies the appropriate platform-specific escaping (single quotes on Unix, double quotes on Windows). If no escaping is needed, the path is copied as-is.

PLATFORM BEHAVIOR:

Unix/Linux/macOS: Uses single quote escaping (escape_shell_single_quotes)
Windows: Uses double quote escaping (escape_shell_double_quotes)

Note: Output buffer must be large enough (worst case: 4x input size for Unix).; Returns false if buffer is too small or escaping fails.; Automatically detects if quoting is needed (no unnecessary escaping).

Example: char escaped[1024];

if (escape_path_for_shell("/usr/local/bin/tool", escaped, sizeof(escaped))) {

// escaped contains the path, properly escaped if needed

}

escape_path_for_shell
bool escape_path_for_shell(const char *path, char *out_buffer, size_t out_buffer_size)
Escape a path for safe use in shell commands (auto-platform)
Definition util/string.c:244

Definition at line 244 of file util/string.c.

                                                                                       {
  if (!path || !out_buffer || out_buffer_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid path or output buffer");
    return false;
  }
 
  // Check if quoting is needed
  if (!string_needs_shell_quoting(path)) {
    // No quoting needed, just copy the path
    size_t path_len = strlen(path);
    if (out_buffer_size <= path_len) {
      SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Output buffer too small for path");
      return false;
    }
    SAFE_STRNCPY(out_buffer, path, out_buffer_size);
    return true;
  }
 
  // Quoting is needed, use platform-specific escaping
#ifdef _WIN32
  return escape_shell_double_quotes(path, out_buffer, out_buffer_size);
#else
  return escape_shell_single_quotes(path, out_buffer, out_buffer_size);
#endif
}

References ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, escape_shell_double_quotes(), escape_shell_single_quotes(), SAFE_STRNCPY, SET_ERRNO, and string_needs_shell_quoting().

Referenced by gpg_sign_with_key().

◆ escape_shell_double_quotes()

bool escape_shell_double_quotes	(	const char *	str,
		char *	out_buffer,
		size_t	out_buffer_size
	)

#include <string.h>

Escape a string for safe use in shell commands (double quotes, Windows-compatible)

Parameters

str	String to escape (must not be NULL)
out_buffer	Output buffer for escaped string (must not be NULL)
out_buffer_size	Size of output buffer (must be > 0)

Returns: true on success, false on failure (buffer too small)

Escapes a string for safe use in shell commands using double quotes, with Windows cmd.exe compatibility. Escapes double quotes and backslashes as required by Windows command-line parsing rules.

ESCAPING STRATEGY:

Input: "C:\Program Files"
Output: "C:\\Program Files"
Double quotes and backslashes are escaped: " -> \", \ -> \

Note: Output buffer must be large enough (worst case: 2x input size + quotes).; Returns false if buffer is too small to hold escaped string.; This escaping method is compatible with Windows cmd.exe and PowerShell.

Warning: Buffer overflow protection is enforced - function fails safely.

Definition at line 174 of file util/string.c.

                                                                                           {
  if (!str || !out_buffer || out_buffer_size == 0) {
    return false;
  }
 
  // Calculate required size: each " becomes \" (2 chars) instead of 1
  // Each \ also needs escaping, so \\ becomes \\\\
  // Worst case: all chars are quotes/backslashes, so we need strlen(str) * 2 + 2 (for surrounding quotes)
  size_t required_size = 2; // Start and end quotes
  for (size_t i = 0; str[i] != '\0'; i++) {
    if (str[i] == '"' || str[i] == '\\') {
      required_size += 2; // \" or '\\'
    } else {
      required_size += 1;
    }
  }
 
  if (out_buffer_size < required_size) {
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Output buffer too small for shell escaping");
    return false;
  }
 
  size_t out_pos = 0;
  out_buffer[out_pos++] = '"'; // Opening quote
 
  for (size_t i = 0; str[i] != '\0'; i++) {
    if (str[i] == '"') {
      // Escape double quote: " becomes \"
      out_buffer[out_pos++] = '\\';
      out_buffer[out_pos++] = '"';
    } else if (str[i] == '\\') {
      // Escape backslash: \ becomes '\\'
      out_buffer[out_pos++] = '\\';
      out_buffer[out_pos++] = '\\';
    } else {
      out_buffer[out_pos++] = str[i];
    }
  }
 
  out_buffer[out_pos++] = '"'; // Closing quote
  out_buffer[out_pos] = '\0';
 
  return true;
}

References ERROR_BUFFER_OVERFLOW, and SET_ERRNO.

Referenced by escape_path_for_shell().

◆ escape_shell_single_quotes()

bool escape_shell_single_quotes	(	const char *	str,
		char *	out_buffer,
		size_t	out_buffer_size
	)

#include <string.h>

Escape a string for safe use in shell commands (single quotes)

Parameters

str	String to escape (must not be NULL)
out_buffer	Output buffer for escaped string (must not be NULL)
out_buffer_size	Size of output buffer (must be > 0)

Returns: true on success, false on failure (buffer too small)

Escapes a string for safe use in Unix shell commands using single quotes. Single quotes in the input are escaped by replacing ' with '\'' (single quote, escaped quote, single quote). This ensures the string is safe for shell evaluation when wrapped in single quotes.

ESCAPING STRATEGY:

Input: "don't"
Output: "don'\''t"
Shell command: echo 'don'\''t' -> prints: don't

Note: Output buffer must be large enough (worst case: 4x input size).; Returns false if buffer is too small to hold escaped string.; This escaping method is compatible with sh, bash, zsh, and other Unix shells.

Warning: Buffer overflow protection is enforced - function fails safely.

Definition at line 132 of file util/string.c.

                                                                                           {
  if (!str || !out_buffer || out_buffer_size == 0) {
    return false;
  }
 
  // Calculate required size: each ' becomes '\'' (4 chars) instead of 1
  // Worst case: all chars are quotes, so we need strlen(str) * 4 + 2 (for surrounding quotes)
  size_t required_size = 2; // Start and end quotes
  for (size_t i = 0; str[i] != '\0'; i++) {
    if (str[i] == '\'') {
      required_size += 4; // '\''
    } else {
      required_size += 1;
    }
  }
 
  if (out_buffer_size < required_size) {
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Output buffer too small for shell escaping");
    return false;
  }
 
  size_t out_pos = 0;
  out_buffer[out_pos++] = '\''; // Opening quote
 
  for (size_t i = 0; str[i] != '\0'; i++) {
    if (str[i] == '\'') {
      // Replace ' with '\'' (close quote, escaped quote, open quote)
      out_buffer[out_pos++] = '\'';
      out_buffer[out_pos++] = '\\';
      out_buffer[out_pos++] = '\'';
      out_buffer[out_pos++] = '\'';
    } else {
      out_buffer[out_pos++] = str[i];
    }
  }
 
  out_buffer[out_pos++] = '\''; // Closing quote
  out_buffer[out_pos] = '\0';
 
  return true;
}

References ERROR_BUFFER_OVERFLOW, and SET_ERRNO.

Referenced by escape_path_for_shell(), and gpg_get_public_key().

◆ expand_ipv6()

asciichat_error_t expand_ipv6	(	const char *	ipv6,
		char *	expanded_out,
		size_t	out_size
	)

#include <ip.h>

Expand IPv6 address to full form.

Parameters

ipv6	IPv6 address (must not be NULL)
expanded_out	Output buffer for expanded form (must not be NULL)
out_size	Size of output buffer

Returns: ASCIICHAT_OK on success, error code on failure

Expands an IPv6 address to its full uncompressed form with all 8 groups of 4 hexadecimal digits each, separated by colons.

EXAMPLES:

"::1" -> "0000:0000:0000:0000:0000:0000:0000:0001"
"2001:db8::1" -> "2001:0db8:0000:0000:0000:0000:0000:0001"
"fe80::1" -> "fe80:0000:0000:0000:0000:0000:0000:0001"

Note: Output buffer should be at least 64 bytes.; Returns error if input is not a valid IPv6 address.

Example: char expanded[64];

if (expand_ipv6("::1", expanded, sizeof(expanded)) == ASCIICHAT_OK) {

// expanded = "0000:0000:0000:0000:0000:0000:0000:0001"

}

expand_ipv6
asciichat_error_t expand_ipv6(const char *ipv6, char *expanded_out, size_t out_size)
Expand IPv6 address to full form.
Definition ip.c:932

Definition at line 932 of file ip.c.

                                                                                     {
  if (!ipv6 || !expanded_out || out_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments to expand_ipv6");
  }
 
  // Normalize (remove brackets)
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ipv6, normalized, sizeof(normalized)) != 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Failed to parse IPv6 address");
  }
 
  // Validate
  if (!is_valid_ipv6(normalized)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IPv6 address: %s", ipv6);
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Failed to convert IPv6 address");
  }
 
  // Format as full expanded form: xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx
  size_t written =
      SAFE_SNPRINTF(expanded_out, out_size, "%04x:%04x:%04x:%04x:%04x:%04x:%04x:%04x",
                    (addr.s6_addr[0] << 8) | addr.s6_addr[1], (addr.s6_addr[2] << 8) | addr.s6_addr[3],
                    (addr.s6_addr[4] << 8) | addr.s6_addr[5], (addr.s6_addr[6] << 8) | addr.s6_addr[7],
                    (addr.s6_addr[8] << 8) | addr.s6_addr[9], (addr.s6_addr[10] << 8) | addr.s6_addr[11],
                    (addr.s6_addr[12] << 8) | addr.s6_addr[13], (addr.s6_addr[14] << 8) | addr.s6_addr[15]);
 
  if (written >= out_size) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Output buffer too small");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, is_valid_ipv6(), parse_ipv6_address(), SAFE_SNPRINTF, and SET_ERRNO.

◆ expand_path()

char * expand_path ( const char * path )

#include <path.h>

Expand path with tilde (~) support.

Parameters

path	Path to expand (may contain ~, must not be NULL)

Returns: Expanded path (must be freed by caller), or NULL on failure

Expands a file path, replacing ~ with the user's home directory. On Unix, uses $HOME environment variable. On Windows, uses USERPROFILE% environment variable.

Note: Returned path is allocated with malloc() and must be freed by caller.; Returns NULL on failure (invalid path, memory allocation error, etc.).; Does not expand environment variables other than ~.

Example: char *expanded = expand_path("~/.config/ascii-chat");

// Returns: "/home/user/.config/ascii-chat" (on Unix)

free(expanded);

expand_path
char * expand_path(const char *path)
Expand path with tilde (~) support.
Definition path.c:505

Definition at line 505 of file path.c.

                                    {
  if (path[0] == PATH_TILDE) {
    const char *home = platform_get_home_dir();
    if (!home) {
      return NULL;
    }
 
    char *expanded;
    size_t total_len = strlen(home) + strlen(path) + 1; // path includes the tilde
    expanded = SAFE_MALLOC(total_len, char *);
    if (!expanded) {
      return NULL;
    }
    safe_snprintf(expanded, total_len, "%s%s", home, path + 1);
 
    platform_normalize_path_separators(expanded);
 
    return expanded;
  }
  return platform_strdup(path);
}

References PATH_TILDE, platform_get_home_dir(), platform_normalize_path_separators(), platform_strdup(), SAFE_MALLOC, and safe_snprintf().

Referenced by config_create_default(), config_load_and_apply(), detect_default_ssh_key(), and path_validate_user_path().

◆ extract_ip_from_address()

int extract_ip_from_address	(	const char *	addr_with_port,
		char *	ip_out,
		size_t	ip_out_size
	)

#include <ip.h>

Extract IP address (without port) from formatted address string.

Extracts the IP address portion from a formatted address that includes a port. Handles both IPv4 (e.g., "192.168.1.1:27224") and IPv6 with brackets (e.g., "[2001:db8::1]:27224").

Parameters

addr_with_port	Formatted address string with port
ip_out	Output buffer for IP address (without port)
ip_out_size	Size of output buffer

Returns: 0 on success, -1 on error

Example: char ip[64];

extract_ip_from_address("192.168.1.1:27224", ip, sizeof(ip));

// ip now contains "192.168.1.1"

extract_ip_from_address("[::1]:27224", ip, sizeof(ip));

// ip now contains "::1"

extract_ip_from_address
int extract_ip_from_address(const char *addr_with_port, char *ip_out, size_t ip_out_size)
Extract IP address (without port) from formatted address string.
Definition ip.c:1053

Definition at line 1053 of file ip.c.

                                                                                          {
  if (!addr_with_port || !ip_out || ip_out_size == 0) {
    return -1;
  }
 
  // Check for IPv6 bracket notation: [2001:db8::1]:27224
  if (addr_with_port[0] == '[') {
    const char *bracket_end = strchr(addr_with_port, ']');
    if (!bracket_end) {
      return -1;
    }
    size_t ip_len = (size_t)(bracket_end - addr_with_port - 1);
    if (ip_len >= ip_out_size) {
      return -1;
    }
    memcpy(ip_out, addr_with_port + 1, ip_len);
    ip_out[ip_len] = '\0';
    return 0;
  }
 
  // IPv4: Find last colon and extract IP part
  const char *colon = strrchr(addr_with_port, ':');
  if (!colon) {
    // No port, just copy the whole thing
    SAFE_STRNCPY(ip_out, addr_with_port, ip_out_size);
    return 0;
  }
 
  size_t ip_len = (size_t)(colon - addr_with_port);
  if (ip_len >= ip_out_size) {
    return -1;
  }
  memcpy(ip_out, addr_with_port, ip_len);
  ip_out[ip_len] = '\0';
  return 0;
}

References SAFE_STRNCPY.

◆ extract_ipv4_from_mapped_ipv6()

asciichat_error_t extract_ipv4_from_mapped_ipv6	(	const char *	ipv6,
		char *	ipv4_out,
		size_t	out_size
	)

#include <ip.h>

Extract IPv4 address from IPv6-mapped format.

Parameters

ipv6	IPv6-mapped address (must not be NULL)
ipv4_out	Output buffer for IPv4 address (must not be NULL)
out_size	Size of output buffer

Returns: ASCIICHAT_OK on success, error code on failure

Extracts the IPv4 address from an IPv6-mapped address (::ffff:x.x.x.x).

INPUT FORMATS:

"::ffff:192.168.1.1" -> "192.168.1.1"
"::ffff:c0a8:0101" (hex notation) -> "192.168.1.1"

Note: Returns error if input is not a valid IPv6-mapped IPv4 address.; Output buffer should be at least 16 bytes.

Example: char ipv4[16];

if (extract_ipv4_from_mapped_ipv6("::ffff:192.168.1.1", ipv4, sizeof(ipv4)) == ASCIICHAT_OK) {

// ipv4 = "192.168.1.1"

}

extract_ipv4_from_mapped_ipv6
asciichat_error_t extract_ipv4_from_mapped_ipv6(const char *ipv6, char *ipv4_out, size_t out_size)
Extract IPv4 address from IPv6-mapped format.
Definition ip.c:896

Definition at line 896 of file ip.c.

                                                                                                   {
  if (!ipv6 || !ipv4_out || out_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments to extract_ipv4_from_mapped_ipv6");
  }
 
  if (!is_ipv4_mapped_ipv6(ipv6)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Not an IPv4-mapped IPv6 address: %s", ipv6);
  }
 
  // Normalize
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ipv6, normalized, sizeof(normalized)) != 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Failed to parse IPv6 address");
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Failed to convert IPv6 address");
  }
 
  // Extract last 4 bytes and format as IPv4
  struct in_addr ipv4_addr;
  memcpy(&ipv4_addr.s_addr, &addr.s6_addr[12], 4);
 
  if (inet_ntop(AF_INET, &ipv4_addr, ipv4_out, (socklen_t)out_size) == NULL) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to format IPv4 address");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, is_ipv4_mapped_ipv6(), parse_ipv6_address(), and SET_ERRNO.

◆ extract_project_relative_path()

const char * extract_project_relative_path ( const char * file )

#include <path.h>

Extract relative path from an absolute path.

Parameters

file	Absolute file path (typically from FILE, must not be NULL)

Returns: Relative path from project directory (e.g., lib/platform/symbols.c), or filename if no project directory found

Extracts a project-relative path from an absolute file path. Searches for common project directories (lib/, src/, tests/, include/) and returns the path relative from that directory. Useful for logging and error reporting where full paths are too verbose.

Note: Handles both Unix (/) and Windows () path separators.; Falls back to just the filename if no project directory found.; Returns a pointer into the input string (does not allocate memory).; Input string must remain valid for the lifetime of the returned pointer.

Example: const char *rel = extract_project_relative_path("/home/user/src/lib/path.c");

// Returns: "lib/path.c"

extract_project_relative_path
const char * extract_project_relative_path(const char *file)
Extract relative path from an absolute path.
Definition path.c:456

Definition at line 456 of file path.c.

                                                            {
  if (!file) {
    SET_ERRNO(ERROR_INVALID_PARAM, "file is null");
    return "unknown";
  }
 
#ifdef __EMSCRIPTEN__
  // WASM builds: Return raw path to avoid recursion in logging system
  // extract_project_relative_path is called from format_log_header, which is part of logging.
  // If we call normalize_path or other functions that might use SET_ERRNO or log functions,
  // we create infinite recursion: log_msg -> format_log_header -> extract_project_relative_path -> SET_ERRNO ->
  // log_error -> log_msg For WASM, just return the filename without path processing.
  const char *sep = strrchr(file, '/');
  if (!sep) {
    sep = strrchr(file, '\\');
  }
  return sep ? sep + 1 : file;
#endif
 
  /* First normalize the path to resolve .. and . components */
  const char *normalized = normalize_path(file);
 
  /* Try to find and strip the project root from the absolute path */
  char *project_root = find_project_root();
  if (project_root) {
    size_t root_len = strlen(project_root);
    size_t norm_len = strlen(normalized);
 
    /* Check if normalized path starts with project root */
    if (norm_len > root_len && strncmp(normalized, project_root, root_len) == 0) {
      const char *remainder = normalized + root_len;
 
      /* Skip the separator if present */
      if (*remainder == PATH_DELIM || *remainder == '/' || *remainder == '\\') {
        remainder++;
      }
 
      free(project_root);
      return remainder;
    }
    free(project_root);
  }
 
  /* Fallback: Project root detection failed, but we should still try to return
   * a meaningful relative path, not just the filename. Return the normalized path
   * which should contain the full directory structure. */
  return normalized;
}

References ERROR_INVALID_PARAM, PATH_DELIM, and SET_ERRNO.

Referenced by asciichat_fatal_with_context(), asciichat_print_error_context(), log_json_async_safe(), log_json_write(), and log_template_apply().

◆ format_bytes_pretty()

void format_bytes_pretty	(	size_t	bytes,
		char *	out,
		size_t	out_capacity
	)

#include <format.h>

Format byte count into human-readable string.

Parameters

bytes	Number of bytes to format
out	Output buffer for formatted string (must not be NULL)
out_capacity	Size of output buffer (must be > 0)

Formats a byte count into a human-readable string with appropriate units. Automatically selects the appropriate unit (B, KB, MB, GB, TB, PB, EB) based on the value. Units step up at 80% of the next tier to avoid awkward transitions. Uses binary units (1024-based) for calculations.

FORMATTING RULES (threshold at 80% of next unit):

0-819 bytes: "N B" (e.g., "512 B")
819-839,339 bytes: "N.NN KB" (e.g., "0.80 KB")
839,339-858,993,459 bytes: "N.NN MB" (e.g., "0.80 MB")
858,993,459-879,609,302,015 bytes: "N.NN GB" (e.g., "0.80 GB")
879,609,302,015-900,719,925,374,591 bytes: "N.NN TB" (e.g., "0.80 TB")
900,719,925,374,591-921,737,309,184,883,711 bytes: "N.NN PB" (e.g., "0.80 PB")
921,737,309,184,883,711 and above: "N.NN EB" (e.g., "0.80 EB")

Note: Output buffer should be at least 32 bytes to accommodate all formats.; Function truncates output if buffer is too small.; Decimal precision is 2 places for units >= KB.; Uses binary units (1024-based), not decimal (1000-based).

Example: char buf[64];

format_bytes_pretty(512, buf, sizeof(buf)); // "512 B"

format_bytes_pretty(819, buf, sizeof(buf)); // "819 B" (just below KB threshold)

format_bytes_pretty(820, buf, sizeof(buf)); // "0.80 KB" (at 80% of 1 KB)

format_bytes_pretty(1048576, buf, sizeof(buf)); // "1.00 MB" (at 100% of 1 MB)

format_bytes_pretty(838860, buf, sizeof(buf)); // "0.80 MB" (at 80% of 1 MB)

format_bytes_pretty(1125899906842624, buf, sizeof(buf)); // "1.00 PB"

format_bytes_pretty(1152921504606846976ULL, buf, sizeof(buf)); // "1.00 EB"

format_bytes_pretty
void format_bytes_pretty(size_t bytes, char *out, size_t out_capacity)
Format byte count into human-readable string.
Definition util/format.c:10

Definition at line 10 of file util/format.c.

                                                                       {
  const double KB = 1024.0;
  const double MB = KB * 1024.0;
  const double GB = MB * 1024.0;
  const double TB = GB * 1024.0;
  const double PB = TB * 1024.0;
  const double EB = PB * 1024.0;
 
  const double THRESHOLD = 0.8;
 
  double byte_val = (double)bytes;
 
  if (byte_val < THRESHOLD * KB) {
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%zu B", bytes));
  } else if (byte_val < THRESHOLD * MB) {
    double value = byte_val / KB;
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%.2f KB", value));
  } else if (byte_val < THRESHOLD * GB) {
    double value = byte_val / MB;
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%.2f MB", value));
  } else if (byte_val < THRESHOLD * TB) {
    double value = byte_val / GB;
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%.2f GB", value));
  } else if (byte_val < THRESHOLD * PB) {
    double value = byte_val / TB;
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%.2f TB", value));
  } else if (byte_val < THRESHOLD * EB) {
    double value = byte_val / PB;
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%.2f PB", value));
  } else {
    double value = byte_val / EB;
    SAFE_IGNORE_PRINTF_RESULT(safe_snprintf(out, out_capacity, "%.2f EB", value));
  }
}

References SAFE_IGNORE_PRINTF_RESULT, and safe_snprintf().

Referenced by buffer_pool_create(), buffer_pool_log_stats(), crypto_destroy(), frame_check_size_overflow(), frame_validate_new(), handle_image_frame_packet(), packet_decode_frame_data_malloc(), and packet_validate_frame_dimensions().

◆ format_ip_address()

asciichat_error_t format_ip_address	(	int	family,
		const struct sockaddr *	addr,
		char *	output,
		size_t	output_size
	)

#include <ip.h>

Format IP address from socket address structure.

Parameters

family	Address family (AF_INET for IPv4 or AF_INET6 for IPv6)
addr	Socket address pointer (must not be NULL)
output	Output buffer for formatted IP address (must not be NULL)
output_size	Size of output buffer (must be > 0)

Returns: ASCIICHAT_OK on success, error code on failure

Formats an IP address from a socket address structure. Automatically handles both IPv4 and IPv6 addresses by extracting the address from the appropriate socket structure fields.

OUTPUT FORMATS:

IPv4: "192.0.2.1"
IPv6: "2001:db8::1"

Note: Output buffer should be at least 64 bytes to accommodate any IPv6 address.; For IPv4: addr should point to sockaddr_in, for IPv6: should point to sockaddr_in6.; Returns error code on failure (invalid family, buffer too small, etc.).

Example: char ip_str[64];

struct sockaddr_in addr;

// ... initialize addr ...

if (format_ip_address(AF_INET, &addr, ip_str, sizeof(ip_str)) == ASCIICHAT_OK) {

// ip_str contains the formatted IP address

}

Definition at line 196 of file ip.c.

                                                                                                               {
  if (!addr || !output || output_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments to format_ip_address");
  }
 
  const void *ip_ptr = NULL;
 
  if (family == AF_INET) {
    const struct sockaddr_in *addr_in = (const struct sockaddr_in *)addr;
    ip_ptr = &addr_in->sin_addr;
  } else if (family == AF_INET6) {
    const struct sockaddr_in6 *addr_in6 = (const struct sockaddr_in6 *)addr;
    ip_ptr = &addr_in6->sin6_addr;
  } else {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Unsupported address family: %d", family);
  }
 
  if (inet_ntop(family, ip_ptr, output, (socklen_t)output_size) == NULL) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to format IP address");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, and SET_ERRNO.

Referenced by tcp_client_connect(), tcp_client_context_get_ip(), and tcp_server_run().

◆ format_ip_with_port()

asciichat_error_t format_ip_with_port	(	const char *	ip,
		uint16_t	port,
		char *	output,
		size_t	output_size
	)

#include <ip.h>

Format IP address with port number.

Parameters

ip	IP address (without brackets, must not be NULL)
port	Port number (0-65535)
output	Output buffer (must not be NULL)
output_size	Size of output buffer (must be > 0)

Returns: ASCIICHAT_OK on success, error code on failure

Formats an IP address with port number. Automatically adds brackets for IPv6 addresses to separate address from port. IPv4 addresses are formatted without brackets.

OUTPUT FORMATS:

IPv4: "192.0.2.1:8080"
IPv6: "[2001:db8::1]:8080"

Note: Output buffer must be large enough (at least 64 bytes recommended).; IPv6 addresses automatically get brackets in output.; Returns error code on failure (buffer too small, invalid address, etc.).

Example: char output[64];

if (format_ip_with_port("::1", 8080, output, sizeof(output)) == ASCIICHAT_OK) {

// output = "[::1]:8080"

}

format_ip_with_port
asciichat_error_t format_ip_with_port(const char *ip, uint16_t port, char *output, size_t output_size)
Format IP address with port number.
Definition ip.c:221

Definition at line 221 of file ip.c.

                                                                                                       {
  if (!ip || !output || output_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: %s", ip);
  }
 
  if (strlen(ip) == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: %s", ip);
  }
 
  if (strlen(ip) > 256) {
    char ip_buffer[BUFFER_SIZE_SMALL];
    SAFE_STRNCPY(ip_buffer, ip, sizeof(ip_buffer));
    return SET_ERRNO(ERROR_INVALID_PARAM, "Suspiciously long ip: %s", ip_buffer);
  }
 
  // Check if it's IPv6 (contains ':')
  if (strchr(ip, ':') != NULL) {
    // IPv6 - use bracket notation
    size_t written = SAFE_SNPRINTF(output, output_size, "[%s]:%u", ip, port);
    if (written >= output_size) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid ip=%s or port=%u", ip, port);
    }
  } else {
    // IPv4 - no brackets
    size_t written = SAFE_SNPRINTF(output, output_size, "%s:%u", ip, port);
    if (written >= output_size) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid ip=%s or port=%u", ip, port);
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, BUFFER_SIZE_SMALL, ERROR_INVALID_PARAM, SAFE_SNPRINTF, SAFE_STRNCPY, and SET_ERRNO.

Referenced by add_known_host(), check_known_host(), check_known_host_no_identity(), display_mitm_warning(), prompt_unknown_host(), prompt_unknown_host_no_identity(), and remove_known_host().

◆ get_config_dir()

char * get_config_dir ( void )

#include <path.h>

Get configuration directory path with XDG_CONFIG_HOME support.

Returns: Path to configuration directory (must be freed by caller), or NULL on failure

Returns the appropriate configuration directory path according to platform conventions and environment variables. The path includes the directory separator at the end for convenience.

All ascii-chat data files use this single directory:

config.toml (configuration)
known_hosts (server key verification)

Configuration path resolution:

Unix: $XDG_CONFIG_HOME/ascii-chat/ if XDG_CONFIG_HOME is set, otherwise ~/.ascii-chat/
Windows: APPDATA%\ascii-chat\ if APPDATA is set, with fallback to USERPROFILE%\AppData\Roaming\ascii-chat\, HOME%.config\ascii-chat\, or C:\ProgramData\ascii-chat\

Note: Returned path is allocated with malloc() and must be freed by caller.; Path includes directory separator at the end (e.g., "/home/user/.config/ascii-chat/").; Returns NULL on failure (memory allocation error, etc.).

Example: char *config_dir = get_config_dir();

// Returns: "/home/user/.config/ascii-chat/" (on Unix with XDG_CONFIG_HOME unset)

// or: "C:\Users\user\AppData\Roaming\ascii-chat\" (on Windows)

free(config_dir);

get_config_dir
char * get_config_dir(void)
Get configuration directory path with XDG_CONFIG_HOME support.
Definition path.c:527

Definition at line 527 of file path.c.

                           {
  /* Delegate to platform abstraction layer */
  return platform_get_config_dir();
}

References platform_get_config_dir().

Referenced by config_load_and_apply(), discovery_keys_get_cache_path(), get_known_hosts_path(), options_init(), and path_validate_user_path().

◆ get_data_dir()

char * get_data_dir ( void )

#include <path.h>

Get application data directory path.

Returns: Path to data directory (must be freed by caller), or NULL on failure

Returns XDG_DATA_HOME/ascii-chat/ on Unix (~/.local/share/ascii-chat/ by default) or AppData\ascii-chat\ on Windows.

Use this for application data files like databases, not configuration files.

Example:: char *data_dir = get_data_dir();

// Returns: "/home/user/.local/share/ascii-chat/" (on Unix)

// or: "C:\Users\user\AppData\Roaming\ascii-chat\" (on Windows)

free(data_dir);

get_data_dir
char * get_data_dir(void)
Get application data directory path.
Definition path.c:532

Definition at line 532 of file path.c.

                         {
  /* Delegate to platform abstraction layer */
  return platform_get_data_dir();
}

References platform_get_data_dir().

Referenced by get_discovery_database_dir().

◆ get_discovery_database_dir()

char * get_discovery_database_dir ( void )

#include <path.h>

Get discovery service database directory with Homebrew-aware system-wide fallback.

Returns: Path to database directory (must be freed by caller), or NULL on failure

Returns the appropriate directory for the discovery service database, with Homebrew-aware system-wide installation support. The path includes a trailing directory separator.

Directory resolution (in order of preference):

System-wide location using baked-in install prefix:
- Unix: ${ASCIICHAT_INSTALL_PREFIX}/var/ascii-chat/ (e.g., /opt/homebrew/var/ascii-chat/ or /usr/local/var/ascii-chat/)
- Windows: PROGRAMDATA%\ascii-chat\
macOS only: /usr/local/var/ascii-chat/ (if different from install prefix, typically user-writable)
User data directory: $XDG_DATA_HOME/ascii-chat/ or ~/.local/share/ascii-chat/

The install prefix is determined at compile time from CMake's CMAKE_INSTALL_PREFIX, which Homebrew sets appropriately:

macOS Apple Silicon: /opt/homebrew
macOS Intel: /usr/local
Linux: /usr/local (default)

The function tries each location and automatically creates directories with appropriate permissions (0755 for system directories, 0700 for user directories). If a location is not writable, it falls back to the next option.

Note: Returned path is allocated with malloc() and must be freed by caller.; Path includes directory separator at the end (e.g., "/opt/homebrew/var/ascii-chat/").; Returns NULL if both system and user data directories are inaccessible.; Creates directories recursively if they don't exist and parent is writable.

Example: char *db_dir = get_discovery_database_dir();

// macOS (Apple Silicon): "/opt/homebrew/var/ascii-chat/", then "/usr/local/var/ascii-chat/"

// macOS (Intel): "/usr/local/var/ascii-chat/"

// Linux: "/usr/local/var/ascii-chat/"

// User fallback: "~/.local/share/ascii-chat/"

free(db_dir);

get_discovery_database_dir
char * get_discovery_database_dir(void)
Get discovery service database directory with Homebrew-aware system-wide fallback.
Definition path.c:624

Definition at line 624 of file path.c.

                                       {
#ifdef _WIN32
  // Windows: Try %PROGRAMDATA%\ascii-chat\ first, then fall back to user directories
  const char *program_data = platform_getenv("PROGRAMDATA");
  if (program_data && program_data[0] != '\0') {
    size_t len = strlen(program_data) + strlen("\\ascii-chat\\") + 1;
    char *system_dir = SAFE_MALLOC(len, char *);
    if (system_dir) {
      safe_snprintf(system_dir, len, "%s\\ascii-chat\\", program_data);
 
      // Try to create directory recursively with public permissions (755 equivalent)
      asciichat_error_t mkdir_result = platform_mkdir_recursive(system_dir, 0755);
      if (mkdir_result == ASCIICHAT_OK) {
        // Directory exists or was created - check if writable
        if (platform_access(system_dir, PLATFORM_ACCESS_WRITE) == 0) {
          return system_dir; // System-wide location is writable
        }
      }
      SAFE_FREE(system_dir);
    }
  }
 
  // Fall back to user data directory
  char *data_dir = get_data_dir();
  if (data_dir) {
    // Try to create the directory recursively
    asciichat_error_t mkdir_result = platform_mkdir_recursive(data_dir, DIR_PERM_PRIVATE);
    if (mkdir_result == ASCIICHAT_OK) {
      if (platform_access(data_dir, PLATFORM_ACCESS_WRITE) == 0) {
        return data_dir;
      }
    }
    SAFE_FREE(data_dir);
  }
 
  return NULL;
#else
  // Unix: Try ${INSTALL_PREFIX}/var/ascii-chat/ first (system-wide, Homebrew-aware)
  // This uses the baked-in install prefix from paths.h (e.g., /opt/homebrew or /usr/local)
  const char *prefix = ASCIICHAT_INSTALL_PREFIX;
  size_t system_len = strlen(prefix) + strlen("/var/ascii-chat/") + 1;
  char *system_dir = SAFE_MALLOC(system_len, char *);
  if (system_dir) {
    safe_snprintf(system_dir, system_len, "%s/var/ascii-chat/", prefix);
 
    // Try to create directory recursively with public permissions (755) for system-wide use
    // platform_mkdir_recursive creates parent directories as needed
    asciichat_error_t mkdir_result = platform_mkdir_recursive(system_dir, 0755);
    if (mkdir_result == ASCIICHAT_OK) {
      // Directory exists or was created - check if writable
      if (platform_access(system_dir, PLATFORM_ACCESS_WRITE) == 0) {
        return system_dir; // System-wide location is writable
      }
    }
    SAFE_FREE(system_dir);
  }
 
#ifdef __APPLE__
  // On macOS, /usr/local is typically user-writable (set up by Homebrew)
  // Try it if the install prefix is different (e.g., /opt/homebrew on Apple Silicon)
  if (strcmp(prefix, "/usr/local") != 0) {
    const char *usr_local_path = "/usr/local/var/ascii-chat/";
    size_t usr_local_len = strlen(usr_local_path) + 1;
    char *usr_local_dir = SAFE_MALLOC(usr_local_len, char *);
    if (usr_local_dir) {
      safe_snprintf(usr_local_dir, usr_local_len, "%s", usr_local_path);
 
      asciichat_error_t mkdir_result = platform_mkdir_recursive(usr_local_dir, 0755);
      if (mkdir_result == ASCIICHAT_OK) {
        if (platform_access(usr_local_dir, PLATFORM_ACCESS_WRITE) == 0) {
          return usr_local_dir; // /usr/local is writable
        }
      }
      SAFE_FREE(usr_local_dir);
    }
  }
#endif
 
  // Fall back to user data directory (XDG_DATA_HOME or ~/.local/share/ascii-chat/)
  char *data_dir = get_data_dir();
  if (data_dir) {
    // Try to create the directory recursively
    asciichat_error_t mkdir_result = platform_mkdir_recursive(data_dir, DIR_PERM_PRIVATE);
    if (mkdir_result == ASCIICHAT_OK) {
      if (platform_access(data_dir, PLATFORM_ACCESS_WRITE) == 0) {
        return data_dir;
      }
    }
    SAFE_FREE(data_dir);
  }
 
  return NULL;
#endif
}

References ASCIICHAT_INSTALL_PREFIX, ASCIICHAT_OK, DIR_PERM_PRIVATE, get_data_dir(), platform_access(), PLATFORM_ACCESS_WRITE, platform_getenv(), platform_mkdir_recursive(), SAFE_FREE, SAFE_MALLOC, and safe_snprintf().

Referenced by options_init().

◆ get_ip_type_string()

const char * get_ip_type_string ( const char * ip )

#include <ip.h>

Get human-readable string describing IP address type.

Classifies an IP address and returns a descriptive string. Possible return values:

"All Interfaces" - Wildcard bind address (0.0.0.0 or ::)
"Localhost" - Loopback address (127.0.0.0/8 or ::1)
"LAN" - Private network address (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, or fc00::/7)
"Internet" - Public internet address
"Unknown" - Invalid or unrecognized address
"" - Empty/null input

Parameters

ip	IP address to classify (without port)

Returns: Constant string describing the IP type

Example: const char *type1 = get_ip_type_string("0.0.0.0"); // Returns "All Interfaces"

const char *type2 = get_ip_type_string("127.0.0.1"); // Returns "Localhost"

const char *type3 = get_ip_type_string("192.168.1.1"); // Returns "LAN"

const char *type4 = get_ip_type_string("8.8.8.8"); // Returns "Internet"

const char *type5 = get_ip_type_string("::1"); // Returns "Localhost"

get_ip_type_string
const char * get_ip_type_string(const char *ip)
Get human-readable string describing IP address type.
Definition ip.c:1091

Definition at line 1091 of file ip.c.

                                               {
  if (!ip || ip[0] == '\0') {
    return "";
  }
 
  // Check for wildcard "bind to all interfaces" addresses
  // IPv4: 0.0.0.0
  if (strcmp(ip, "0.0.0.0") == 0) {
    return "All Interfaces";
  }
 
  // IPv6: :: (unspecified address)
  if (strcmp(ip, "::") == 0) {
    return "All Interfaces";
  }
 
  // Check IPv4
  if (is_localhost_ipv4(ip)) {
    return "Localhost";
  }
  if (is_lan_ipv4(ip)) {
    return "LAN";
  }
  if (is_internet_ipv4(ip)) {
    return "Internet";
  }
 
  // Check IPv6
  if (is_localhost_ipv6(ip)) {
    return "Localhost";
  }
  if (is_lan_ipv6(ip)) {
    return "LAN";
  }
  if (is_internet_ipv6(ip)) {
    return "Internet";
  }
 
  return "Unknown";
}

References is_internet_ipv4(), is_internet_ipv6(), is_lan_ipv4(), is_lan_ipv6(), is_localhost_ipv4(), and is_localhost_ipv6().

◆ get_ip_version()

int get_ip_version ( const char * ip )

#include <ip.h>

Get IP address version.

Parameters

ip	IP address string (must not be NULL)

Returns: 4 for IPv4, 6 for IPv6, 0 for invalid

Detects the version of an IP address without validating its full correctness. Useful for protocol selection and dual-stack handling.

Note: Returns 0 for NULL, empty strings, or invalid addresses.; Does not validate address correctness beyond basic format.

Example: int version = get_ip_version("192.168.1.1"); // Returns 4

int version = get_ip_version("::1"); // Returns 6

int version = get_ip_version("invalid"); // Returns 0

Definition at line 510 of file ip.c.

                                   {
  if (!ip || strlen(ip) == 0) {
    return 0;
  }
 
  // Quick heuristic: if it contains a colon, it's likely IPv6
  // (unless it's a port separator, but we're just checking the IP part)
  if (strchr(ip, ':') != NULL) {
    // Could be IPv6 or bracketed IPv6
    if (is_valid_ipv6(ip)) {
      return 6;
    }
    return 0; // Has colon but not valid IPv6
  }
 
  // No colon, check if it's IPv4
  if (is_valid_ipv4(ip)) {
    return 4;
  }
 
  return 0; // Not valid IPv4 or IPv6
}

References is_valid_ipv4(), and is_valid_ipv6().

Referenced by compare_ip_port_strings(), ip_compare(), ip_equals(), ip_in_cidr_parsed(), and parse_cidr().

◆ get_log_dir()

char * get_log_dir ( void )

#include <path.h>

Get log directory path appropriate for current build type.

Returns: Path to log directory (must be freed by caller), or NULL on failure

Returns the appropriate log directory path based on build type. The directory is created if it doesn't exist (for release builds). The path does NOT include a trailing directory separator.

Log directory resolution:

Debug builds: Current working directory (for fast iteration)
Release builds: $TMPDIR/ascii-chat/ (Unix: /tmp/ascii-chat/, Windows: TEMP%\ascii-chat)

For release builds, this function automatically creates the ascii-chat subdirectory if it doesn't exist and verifies it's writable.

Note: Returned path is allocated with malloc() and must be freed by caller.; Path does NOT include directory separator at the end.; Returns NULL on failure (memory allocation error, directory creation failed, etc.).; For release builds, the directory is created with 0700 permissions (owner-only).

Example (Debug Build): char *log_dir = get_log_dir();

// Returns: "/home/user/myproject" (current working directory)

free(log_dir);

get_log_dir
char * get_log_dir(void)
Get log directory path appropriate for current build type.
Definition path.c:537

Example (Release Build): char *log_dir = get_log_dir();

// Returns: "/tmp/ascii-chat" (on Unix)

// or: "C:\Users\user\AppData\Local\Temp\ascii-chat" (on Windows)

free(log_dir);

Definition at line 537 of file path.c.

                        {
#ifdef __EMSCRIPTEN__
  // WASM builds: Return NULL to skip SAFE_MALLOC before memory tracking is initialized
  // The caller will use a fallback path (temp dir + filename)
  return NULL;
#endif
 
#ifdef NDEBUG
  // Release builds: Use $TMPDIR/ascii-chat/
  // Get system temp directory
  char temp_dir[PLATFORM_MAX_PATH_LENGTH];
  if (!platform_get_temp_dir(temp_dir, sizeof(temp_dir))) {
    // Fallback: Use current working directory if temp dir unavailable
    char cwd_buf[PLATFORM_MAX_PATH_LENGTH];
    if (!platform_get_cwd(cwd_buf, sizeof(cwd_buf))) {
      return NULL;
    }
    char *result = SAFE_MALLOC(strlen(cwd_buf) + 1, char *);
    if (!result) {
      return NULL;
    }
    safe_snprintf(result, strlen(cwd_buf) + 1, "%s", cwd_buf);
    return result;
  }
 
  // Build path to ascii-chat subdirectory
  size_t log_dir_len = strlen(temp_dir) + strlen(PATH_SEPARATOR_STR) + strlen("ascii-chat") + 1;
  char *log_dir = SAFE_MALLOC(log_dir_len, char *);
  if (!log_dir) {
    return NULL;
  }
  safe_snprintf(log_dir, log_dir_len, "%s%sascii-chat", temp_dir, PATH_SEPARATOR_STR);
 
  // Create the directory if it doesn't exist (with owner-only permissions)
  asciichat_error_t mkdir_result = platform_mkdir(log_dir, DIR_PERM_PRIVATE);
  if (mkdir_result != ASCIICHAT_OK) {
    // Directory creation failed - fall back to temp_dir without subdirectory
    SAFE_FREE(log_dir);
    char *result = SAFE_MALLOC(strlen(temp_dir) + 1, char *);
    if (!result) {
      return NULL;
    }
    safe_snprintf(result, strlen(temp_dir) + 1, "%s", temp_dir);
    return result;
  }
 
  // Verify the directory is writable
  if (platform_access(log_dir, PLATFORM_ACCESS_WRITE) != 0) {
    // Directory not writable - fall back to temp_dir
    SAFE_FREE(log_dir);
    char *result = SAFE_MALLOC(strlen(temp_dir) + 1, char *);
    if (!result) {
      return NULL;
    }
    safe_snprintf(result, strlen(temp_dir) + 1, "%s", temp_dir);
    return result;
  }
 
  return log_dir;
#else
  // Debug builds: Use repository root for logs.
  // find_project_root() returns a raw malloc() allocation (to avoid debug_malloc
  // recursion), but callers free with SAFE_FREE. Re-allocate with SAFE_MALLOC
  // so the allocator matches.
  char *repo_root = find_project_root();
  if (repo_root) {
    size_t len = strlen(repo_root) + 1;
    char *result = SAFE_MALLOC(len, char *);
    if (result) {
      memcpy(result, repo_root, len);
    }
    free(repo_root);
    return result;
  }
 
  // Fallback to current working directory if repo root not found
  char cwd_buf[PLATFORM_MAX_PATH_LENGTH];
  if (!platform_get_cwd(cwd_buf, sizeof(cwd_buf))) {
    return NULL;
  }
 
  char *result = SAFE_MALLOC(strlen(cwd_buf) + 1, char *);
  safe_snprintf(result, strlen(cwd_buf) + 1, "%s", cwd_buf);
  return result;
#endif
}

References ASCIICHAT_OK, DIR_PERM_PRIVATE, PATH_SEPARATOR_STR, platform_access(), PLATFORM_ACCESS_WRITE, platform_get_cwd(), platform_get_temp_dir(), PLATFORM_MAX_PATH_LENGTH, platform_mkdir(), SAFE_FREE, SAFE_MALLOC, and safe_snprintf().

◆ ip_compare()

int ip_compare	(	const char *	ip1,
		const char *	ip2
	)

#include <ip.h>

Compare two IP addresses for sorting.

Parameters

ip1	First IP address (must not be NULL)
ip2	Second IP address (must not be NULL)

Returns: -1 if ip1 < ip2, 0 if equal, 1 if ip1 > ip2, -2 on error

Compares two IP addresses for sorting. IPv4 addresses sort before IPv6. Within the same version, compares numerically (not lexicographically).

SORT ORDER:

Invalid addresses sort last
IPv4 addresses sort before IPv6
Within IPv4: numeric comparison (10.0.0.1 < 192.168.1.1)
Within IPv6: numeric comparison (::1 < 2001::1)

Note: Returns -2 if either address is invalid.; Useful for qsort() callbacks.

Example: int result = ip_compare("10.0.0.1", "192.168.1.1"); // Returns -1

int result = ip_compare("::1", "192.168.1.1"); // Returns 1 (IPv6 > IPv4)

ip_compare
int ip_compare(const char *ip1, const char *ip2)
Compare two IP addresses for sorting.
Definition ip.c:601

Definition at line 601 of file ip.c.

                                                 {
  if (!ip1 || !ip2) {
    return -2; // Error
  }
 
  int v1 = get_ip_version(ip1);
  int v2 = get_ip_version(ip2);
 
  // Invalid addresses sort last
  if (v1 == 0 && v2 == 0) {
    return 0; // Both invalid, consider equal
  }
  if (v1 == 0) {
    return 1; // ip1 invalid, sorts after ip2
  }
  if (v2 == 0) {
    return -1; // ip2 invalid, sorts after ip1
  }
 
  // IPv4 sorts before IPv6
  if (v1 != v2) {
    return (v1 < v2) ? -1 : 1;
  }
 
  if (v1 == 4) {
    // IPv4: compare numerically
    struct in_addr addr1, addr2;
    if (inet_pton(AF_INET, ip1, &addr1) != 1 || inet_pton(AF_INET, ip2, &addr2) != 1) {
      return -2; // Error
    }
 
    uint32_t val1 = ntohl(addr1.s_addr);
    uint32_t val2 = ntohl(addr2.s_addr);
 
    if (val1 < val2)
      return -1;
    if (val1 > val2)
      return 1;
    return 0;
  } else {
    // IPv6: compare byte by byte
    char norm1[INET6_ADDRSTRLEN], norm2[INET6_ADDRSTRLEN];
 
    if (parse_ipv6_address(ip1, norm1, sizeof(norm1)) != 0) {
      return -2;
    }
    if (parse_ipv6_address(ip2, norm2, sizeof(norm2)) != 0) {
      return -2;
    }
 
    struct in6_addr addr1, addr2;
    if (inet_pton(AF_INET6, norm1, &addr1) != 1 || inet_pton(AF_INET6, norm2, &addr2) != 1) {
      return -2;
    }
 
    return memcmp(&addr1, &addr2, sizeof(addr1));
  }
}

References get_ip_version(), and parse_ipv6_address().

◆ ip_equals()

int ip_equals	(	const char *	ip1,
		const char *	ip2
	)

#include <ip.h>

Compare two IP addresses for equality.

Parameters

ip1	First IP address (must not be NULL)
ip2	Second IP address (must not be NULL)

Returns: 1 if equal, 0 if not equal or invalid

Compares two IP addresses for equality, handling normalization automatically. Works with IPv4 and IPv6, including bracketed IPv6 notation.

NORMALIZATION RULES:

IPv6 addresses are normalized before comparison
Brackets are ignored: "[::1]" equals "::1"
IPv6 zero compression is normalized: "::1" equals "0:0:0:0:0:0:0:1"
IPv4 and IPv6 are never equal

Note: Returns 0 if either address is invalid.; Case-insensitive for IPv6 (A-F vs a-f).

Example: if (ip_equals("::1", "[::1]")) {

// True - brackets ignored

}

if (ip_equals("192.168.1.1", "192.168.1.2")) {

// False - different addresses

}

Definition at line 557 of file ip.c.

                                                {
  if (!ip1 || !ip2) {
    return 0;
  }
 
  // Get versions
  int v1 = get_ip_version(ip1);
  int v2 = get_ip_version(ip2);
 
  // If different versions or either invalid, not equal
  if (v1 != v2 || v1 == 0) {
    return 0;
  }
 
  if (v1 == 4) {
    // IPv4: direct string comparison after validation
    struct in_addr addr1, addr2;
    if (inet_pton(AF_INET, ip1, &addr1) != 1 || inet_pton(AF_INET, ip2, &addr2) != 1) {
      return 0;
    }
    return addr1.s_addr == addr2.s_addr;
  } else {
    // IPv6: normalize then compare
    char norm1[INET6_ADDRSTRLEN], norm2[INET6_ADDRSTRLEN];
 
    // Remove brackets if present
    if (parse_ipv6_address(ip1, norm1, sizeof(norm1)) != 0) {
      return 0;
    }
    if (parse_ipv6_address(ip2, norm2, sizeof(norm2)) != 0) {
      return 0;
    }
 
    // Parse to binary and compare
    struct in6_addr addr1, addr2;
    if (inet_pton(AF_INET6, norm1, &addr1) != 1 || inet_pton(AF_INET6, norm2, &addr2) != 1) {
      return 0;
    }
 
    return memcmp(&addr1, &addr2, sizeof(addr1)) == 0;
  }
}

References get_ip_version(), and parse_ipv6_address().

Referenced by compare_ip_port_strings().

◆ ip_in_cidr()

int ip_in_cidr	(	const char *	ip,
		const char *	cidr
	)

#include <ip.h>

Check if IP address is within CIDR range.

Parameters

ip	IP address to check (must not be NULL)
cidr	CIDR range (e.g., "192.168.1.0/24", must not be NULL)

Returns: 1 if IP is in range, 0 if not or on error

Checks if an IP address falls within a CIDR range. Automatically handles both IPv4 and IPv6. IP and CIDR must be the same version.

EXAMPLES:

"192.168.1.10" in "192.168.1.0/24" -> true
"192.168.2.10" in "192.168.1.0/24" -> false
"2001:db8::1" in "2001:db8::/32" -> true

Note: Returns 0 if IP and CIDR are different versions (IPv4 vs IPv6).; Returns 0 on error (invalid IP, invalid CIDR).

Example: if (ip_in_cidr("192.168.1.10", "192.168.1.0/24")) {

// IP is in the 192.168.1.0/24 subnet

}

ip_in_cidr
int ip_in_cidr(const char *ip, const char *cidr)
Check if IP address is within CIDR range.
Definition ip.c:820

Definition at line 820 of file ip.c.

                                                 {
  if (!ip || !cidr) {
    return 0;
  }
 
  char network[64];
  int prefix;
 
  if (parse_cidr(cidr, network, sizeof(network), &prefix) != 0) {
    return 0; // Invalid CIDR
  }
 
  return ip_in_cidr_parsed(ip, network, prefix);
}

References ip_in_cidr_parsed(), and parse_cidr().

◆ ip_in_cidr_parsed()

int ip_in_cidr_parsed	(	const char *	ip,
		const char *	network,
		int	prefix_len
	)

#include <ip.h>

Check if IP is within CIDR range (parsed form)

Parameters

ip	IP address to check (must not be NULL)
network	Network address (must not be NULL)
prefix_len	Prefix length (0-32 for IPv4, 0-128 for IPv6)

Returns: 1 if IP is in range, 0 if not or on error

Checks if an IP address falls within a CIDR range using pre-parsed network address and prefix length. More efficient than ip_in_cidr() when checking multiple IPs against the same range.

Note: IP and network must be the same version.; Returns 0 on error (invalid IP, invalid network, out of range prefix).

Example: if (ip_in_cidr_parsed("192.168.1.10", "192.168.1.0", 24)) {

// IP is in the 192.168.1.0/24 subnet

}

Definition at line 766 of file ip.c.

                                                                           {
  if (!ip || !network) {
    return 0;
  }
 
  int ip_version = get_ip_version(ip);
  int net_version = get_ip_version(network);
 
  // Must be same version
  if (ip_version != net_version || ip_version == 0) {
    return 0;
  }
 
  if (ip_version == 4) {
    // IPv4 comparison
    struct in_addr ip_addr, net_addr;
    if (inet_pton(AF_INET, ip, &ip_addr) != 1 || inet_pton(AF_INET, network, &net_addr) != 1) {
      return 0;
    }
 
    uint32_t ip_val = ntohl(ip_addr.s_addr);
    uint32_t net_val = ntohl(net_addr.s_addr);
 
    uint32_t ip_masked = apply_ipv4_mask(ip_val, prefix_len);
    uint32_t net_masked = apply_ipv4_mask(net_val, prefix_len);
 
    return ip_masked == net_masked;
  } else {
    // IPv6 comparison
    char ip_norm[INET6_ADDRSTRLEN], net_norm[INET6_ADDRSTRLEN];
 
    if (parse_ipv6_address(ip, ip_norm, sizeof(ip_norm)) != 0) {
      return 0;
    }
    if (parse_ipv6_address(network, net_norm, sizeof(net_norm)) != 0) {
      return 0;
    }
 
    struct in6_addr ip_addr, net_addr;
    if (inet_pton(AF_INET6, ip_norm, &ip_addr) != 1 || inet_pton(AF_INET6, net_norm, &net_addr) != 1) {
      return 0;
    }
 
    // Apply mask to both addresses
    struct in6_addr ip_masked = ip_addr;
    struct in6_addr net_masked = net_addr;
    apply_ipv6_mask(&ip_masked, prefix_len);
    apply_ipv6_mask(&net_masked, prefix_len);
 
    return memcmp(&ip_masked, &net_masked, sizeof(ip_masked)) == 0;
  }
}

References get_ip_version(), and parse_ipv6_address().

Referenced by ip_in_cidr().

◆ ipv4_to_ipv6_mapped()

asciichat_error_t ipv4_to_ipv6_mapped	(	const char *	ipv4,
		char *	ipv6_out,
		size_t	out_size
	)

#include <ip.h>

Convert IPv4 address to IPv6-mapped format.

Parameters

ipv4	IPv4 address (must not be NULL)
ipv6_out	Output buffer for IPv6-mapped address (must not be NULL)
out_size	Size of output buffer

Returns: ASCIICHAT_OK on success, error code on failure

Converts an IPv4 address to IPv6-mapped format (::ffff:x.x.x.x). This format allows IPv4 addresses to be represented in IPv6.

OUTPUT FORMAT: "::ffff:192.168.1.1"

Note: Output buffer should be at least 64 bytes.; Returns error if input is not a valid IPv4 address.

Example: char ipv6[64];

if (ipv4_to_ipv6_mapped("192.168.1.1", ipv6, sizeof(ipv6)) == ASCIICHAT_OK) {

// ipv6 = "::ffff:192.168.1.1"

}

ipv4_to_ipv6_mapped
asciichat_error_t ipv4_to_ipv6_mapped(const char *ipv4, char *ipv6_out, size_t out_size)
Convert IPv4 address to IPv6-mapped format.
Definition ip.c:840

Definition at line 840 of file ip.c.

                                                                                         {
  if (!ipv4 || !ipv6_out || out_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments to ipv4_to_ipv6_mapped");
  }
 
  // Validate IPv4
  if (!is_valid_ipv4(ipv4)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IPv4 address: %s", ipv4);
  }
 
  // Format as ::ffff:x.x.x.x
  size_t written = SAFE_SNPRINTF(ipv6_out, out_size, "::ffff:%s", ipv4);
  if (written >= out_size) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Output buffer too small");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, is_valid_ipv4(), SAFE_SNPRINTF, and SET_ERRNO.

◆ is_anycast_ipv6()

int is_anycast_ipv6 ( const char * ipv6 )

#include <ip.h>

Check if IPv6 address is anycast.

Parameters

ipv6	IPv6 address (must not be NULL)

Returns: 1 if anycast, 0 otherwise

Checks if an IPv6 address is a known anycast address. Anycast addresses are typically indistinguishable from unicast, but some well-known ranges exist:

Subnet-router anycast: last address in each subnet with all host bits zero
6to4 relay anycast: 192.88.99.0/24 (mapped to 2002:c058:6301::)

Note: This function only detects known anycast ranges.; Most anycast addresses cannot be detected without network context.; Returns 0 for invalid IPv6 addresses.

Example: if (is_anycast_ipv6("2002:c058:6301::")) {

// This is a 6to4 relay anycast address

}

is_anycast_ipv6
int is_anycast_ipv6(const char *ipv6)
Check if IPv6 address is anycast.
Definition ip.c:1004

Definition at line 1004 of file ip.c.

                                      {
  if (!ipv6) {
    return 0;
  }
 
  // Normalize
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ipv6, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // 6to4 relay anycast: 192.88.99.0/24 (mapped to 2002:c058:6301::)
  // Check if it matches 2002:c058:6301::
  if (addr.s6_addr[0] == 0x20 && addr.s6_addr[1] == 0x02 && addr.s6_addr[2] == 0xc0 && addr.s6_addr[3] == 0x58 &&
      addr.s6_addr[4] == 0x63 && addr.s6_addr[5] == 0x01) {
    // Check if remaining bytes are zero (anycast)
    int is_zero = 1;
    for (int i = 6; i < 16; i++) {
      if (addr.s6_addr[i] != 0) {
        is_zero = 0;
        break;
      }
    }
    if (is_zero) {
      return 1;
    }
  }
 
  // Subnet-router anycast: would need subnet context to determine
  // We can't detect this without knowing the subnet
 
  return 0;
}

References is_valid_ipv6(), and parse_ipv6_address().

◆ is_broadcast_ipv4()

int is_broadcast_ipv4 ( const char * ip )

#include <ip.h>

Check if IPv4 address is a broadcast address.

Parameters

ip	IPv4 address string (must not be NULL)

Returns: 1 if broadcast address, 0 otherwise

Checks if an IPv4 address is the limited broadcast address:

255.255.255.255

Note: Subnet-specific broadcast addresses (e.g., 192.168.1.255 for 192.168.1.0/24) cannot be determined without network mask information.; Returns 0 for invalid IPv4 addresses.

Example: if (is_broadcast_ipv4("255.255.255.255")) {

// This is the limited broadcast address

}

is_broadcast_ipv4
int is_broadcast_ipv4(const char *ip)
Check if IPv4 address is a broadcast address.
Definition ip.c:1247

Definition at line 1247 of file ip.c.

                                      {
  if (!is_valid_ipv4(ip)) {
    return 0;
  }
 
  struct in_addr addr;
  if (inet_pton(AF_INET, ip, &addr) != 1) {
    return 0;
  }
 
  uint32_t ip_val = ntohl(addr.s_addr);
 
  // Limited broadcast: 255.255.255.255
  if (ip_val == 0xFFFFFFFF) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv4().

Referenced by is_internet_ipv4().

◆ is_broadcast_ipv6()

int is_broadcast_ipv6 ( const char * ip )

#include <ip.h>

Check if IPv6 address is a multicast address.

Parameters

ip	IPv6 address string (must not be NULL)

Returns: 1 if multicast address, 0 otherwise

Checks if an IPv6 address is in the multicast range:

ff00::/8 (ff00:: - ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff)

Note: IPv6 doesn't have broadcast; multicast is used instead.; Returns 0 for invalid IPv6 addresses.

Example: if (is_broadcast_ipv6("ff02::1")) {

// This is a multicast address (all-nodes link-local)

}

is_broadcast_ipv6
int is_broadcast_ipv6(const char *ip)
Check if IPv6 address is a multicast address.
Definition ip.c:1268

Definition at line 1268 of file ip.c.

                                      {
  if (!ip) {
    return 0;
  }
 
  // Remove brackets if present
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ip, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate the normalized address
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // ff00::/8: Multicast addresses
  // First byte should be 0xff
  if (addr.s6_addr[0] == 0xFF) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv6(), and parse_ipv6_address().

Referenced by is_internet_ipv6().

◆ is_internet_ipv4()

int is_internet_ipv4 ( const char * ip )

#include <ip.h>

Check if IPv4 address is a public internet address.

Parameters

ip	IPv4 address string (must not be NULL)

Returns: 1 if public internet address, 0 otherwise

Checks if an IPv4 address is a globally routable public address. Returns 0 for:

Private/LAN addresses (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
Loopback addresses (127.0.0.0/8)
Link-local addresses (169.254.0.0/16)
Broadcast addresses (255.255.255.255)
Multicast addresses (224.0.0.0/4)
Reserved/special use addresses
Invalid addresses

Note: Returns 0 for invalid IPv4 addresses.

Example: if (is_internet_ipv4("8.8.8.8")) {

// This is a public internet address

}

Definition at line 1408 of file ip.c.

                                     {
  if (!is_valid_ipv4(ip)) {
    return 0;
  }
 
  struct in_addr addr;
  if (inet_pton(AF_INET, ip, &addr) != 1) {
    return 0;
  }
 
  uint32_t ip_val = ntohl(addr.s_addr);
 
  // Exclude private/LAN addresses
  if (is_lan_ipv4(ip)) {
    return 0;
  }
 
  // Exclude loopback
  if (is_localhost_ipv4(ip)) {
    return 0;
  }
 
  // Exclude link-local
  if (is_link_local_ipv4(ip)) {
    return 0;
  }
 
  // Exclude broadcast
  if (is_broadcast_ipv4(ip)) {
    return 0;
  }
 
  // Exclude multicast: 224.0.0.0/4
  if ((ip_val & 0xF0000000) == 0xE0000000) {
    return 0;
  }
 
  // Exclude 0.0.0.0/8: "This network"
  if ((ip_val & 0xFF000000) == 0x00000000) {
    return 0;
  }
 
  // Exclude 100.64.0.0/10: Shared Address Space (RFC 6598)
  if ((ip_val & 0xFFC00000) == 0x64400000) {
    return 0;
  }
 
  // Exclude 192.0.0.0/24: IETF Protocol Assignments
  if ((ip_val & 0xFFFFFF00) == 0xC0000000) {
    return 0;
  }
 
  // Exclude 192.0.2.0/24: TEST-NET-1
  if ((ip_val & 0xFFFFFF00) == 0xC0000200) {
    return 0;
  }
 
  // Exclude 198.18.0.0/15: Benchmarking
  if ((ip_val & 0xFFFE0000) == 0xC6120000) {
    return 0;
  }
 
  // Exclude 198.51.100.0/24: TEST-NET-2
  if ((ip_val & 0xFFFFFF00) == 0xC6336400) {
    return 0;
  }
 
  // Exclude 203.0.113.0/24: TEST-NET-3
  if ((ip_val & 0xFFFFFF00) == 0xCB007100) {
    return 0;
  }
 
  // Exclude 240.0.0.0/4: Reserved for future use
  if ((ip_val & 0xF0000000) == 0xF0000000) {
    return 0;
  }
 
  // If none of the exclusions matched, it's a public internet address
  return 1;
}

References is_broadcast_ipv4(), is_lan_ipv4(), is_link_local_ipv4(), is_localhost_ipv4(), and is_valid_ipv4().

Referenced by get_ip_type_string().

◆ is_internet_ipv6()

int is_internet_ipv6 ( const char * ip )

#include <ip.h>

Check if IPv6 address is a public internet address.

Parameters

ip	IPv6 address string (must not be NULL)

Returns: 1 if public internet address, 0 otherwise

Checks if an IPv6 address is a globally routable public address. Returns 0 for:

Loopback address (::1)
Link-local addresses (fe80::/10)
Unique local addresses (fc00::/7)
Multicast addresses (ff00::/8)
Special use/reserved addresses
Invalid addresses

Note: Returns 0 for invalid IPv6 addresses.

Example: if (is_internet_ipv6("2001:4860:4860::8888")) {

// This is a public internet address

}

Definition at line 1490 of file ip.c.

                                     {
  if (!ip) {
    return 0;
  }
 
  // Remove brackets if present
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ip, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate the normalized address
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // Exclude loopback
  if (is_localhost_ipv6(ip)) {
    return 0;
  }
 
  // Exclude link-local
  if (is_link_local_ipv6(ip)) {
    return 0;
  }
 
  // Exclude ULA
  if (is_lan_ipv6(ip)) {
    return 0;
  }
 
  // Exclude multicast
  if (is_broadcast_ipv6(ip)) {
    return 0;
  }
 
  // Exclude unspecified address: ::
  int is_unspecified = 1;
  for (int i = 0; i < 16; i++) {
    if (addr.s6_addr[i] != 0) {
      is_unspecified = 0;
      break;
    }
  }
  if (is_unspecified) {
    return 0;
  }
 
  // Exclude IPv4-mapped IPv6: ::ffff:0:0/96
  if (addr.s6_addr[0] == 0 && addr.s6_addr[1] == 0 && addr.s6_addr[2] == 0 && addr.s6_addr[3] == 0 &&
      addr.s6_addr[4] == 0 && addr.s6_addr[5] == 0 && addr.s6_addr[6] == 0 && addr.s6_addr[7] == 0 &&
      addr.s6_addr[8] == 0 && addr.s6_addr[9] == 0 && addr.s6_addr[10] == 0xFF && addr.s6_addr[11] == 0xFF) {
    return 0;
  }
 
  // Exclude IPv4-compatible IPv6: ::/96 (deprecated)
  if (addr.s6_addr[0] == 0 && addr.s6_addr[1] == 0 && addr.s6_addr[2] == 0 && addr.s6_addr[3] == 0 &&
      addr.s6_addr[4] == 0 && addr.s6_addr[5] == 0 && addr.s6_addr[6] == 0 && addr.s6_addr[7] == 0 &&
      addr.s6_addr[8] == 0 && addr.s6_addr[9] == 0 && addr.s6_addr[10] == 0 && addr.s6_addr[11] == 0) {
    // But not ::, which we already excluded above
    if (addr.s6_addr[12] != 0 || addr.s6_addr[13] != 0 || addr.s6_addr[14] != 0 || addr.s6_addr[15] != 0) {
      return 0;
    }
  }
 
  // Exclude documentation prefix: 2001:db8::/32
  if (addr.s6_addr[0] == 0x20 && addr.s6_addr[1] == 0x01 && addr.s6_addr[2] == 0x0D && addr.s6_addr[3] == 0xB8) {
    return 0;
  }
 
  // Exclude 6to4: 2002::/16
  if (addr.s6_addr[0] == 0x20 && addr.s6_addr[1] == 0x02) {
    return 0;
  }
 
  // If none of the exclusions matched, it's likely a global unicast address
  // Global unicast is typically 2000::/3, but let's accept anything that's not excluded
  return 1;
}

References is_broadcast_ipv6(), is_lan_ipv6(), is_link_local_ipv6(), is_localhost_ipv6(), is_valid_ipv6(), and parse_ipv6_address().

Referenced by get_ip_type_string().

◆ is_ipv4_mapped_ipv6()

int is_ipv4_mapped_ipv6 ( const char * ipv6 )

#include <ip.h>

Check if IPv6 address is IPv4-mapped.

Parameters

ipv6	IPv6 address (must not be NULL)

Returns: 1 if IPv4-mapped, 0 otherwise

Checks if an IPv6 address is in IPv4-mapped format (::ffff:x.x.x.x/96).

Note: Returns 0 for invalid IPv6 addresses.

Example: if (is_ipv4_mapped_ipv6("::ffff:192.168.1.1")) {

// This is an IPv4-mapped IPv6 address

}

Definition at line 860 of file ip.c.

                                          {
  if (!ipv6) {
    return 0;
  }
 
  // Normalize (remove brackets)
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ipv6, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate IPv6
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // Check for ::ffff:0:0/96 prefix
  // First 10 bytes should be 0, next 2 should be 0xff
  for (int i = 0; i < 10; i++) {
    if (addr.s6_addr[i] != 0) {
      return 0;
    }
  }
  if (addr.s6_addr[10] != 0xFF || addr.s6_addr[11] != 0xFF) {
    return 0;
  }
 
  return 1;
}

References is_valid_ipv6(), and parse_ipv6_address().

Referenced by extract_ipv4_from_mapped_ipv6().

◆ is_lan_ipv4()

int is_lan_ipv4 ( const char * ip )

#include <ip.h>

Check if IPv4 address is a private/LAN address.

Parameters

ip	IPv4 address string (must not be NULL)

Returns: 1 if LAN address, 0 otherwise

Checks if an IPv4 address is in private address ranges:

10.0.0.0/8 (10.0.0.0 - 10.255.255.255)
172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
192.168.0.0/16 (192.168.0.0 - 192.168.255.255)

Note: Returns 0 for invalid IPv4 addresses.

Example: if (is_lan_ipv4("192.168.1.1")) {

// This is a private LAN address

}

Definition at line 1185 of file ip.c.

                                {
  if (!is_valid_ipv4(ip)) {
    return 0;
  }
 
  struct in_addr addr;
  if (inet_pton(AF_INET, ip, &addr) != 1) {
    return 0;
  }
 
  uint32_t ip_val = ntohl(addr.s_addr);
 
  // 10.0.0.0/8: 10.0.0.0 - 10.255.255.255
  if ((ip_val & 0xFF000000) == 0x0A000000) {
    return 1;
  }
 
  // 172.16.0.0/12: 172.16.0.0 - 172.31.255.255
  if ((ip_val & 0xFFF00000) == 0xAC100000) {
    return 1;
  }
 
  // 192.168.0.0/16: 192.168.0.0 - 192.168.255.255
  if ((ip_val & 0xFFFF0000) == 0xC0A80000) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv4().

Referenced by get_ip_type_string(), and is_internet_ipv4().

◆ is_lan_ipv6()

int is_lan_ipv6 ( const char * ip )

#include <ip.h>

Check if IPv6 address is a private/LAN address.

Parameters

ip	IPv6 address string (must not be NULL)

Returns: 1 if LAN address, 0 otherwise

Checks if an IPv6 address is a Unique Local Address (ULA):

fc00::/7 (fc00:: - fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff)

Note: Returns 0 for invalid IPv6 addresses.

Example: if (is_lan_ipv6("fc00::1")) {

// This is a private ULA address

}

Definition at line 1216 of file ip.c.

                                {
  if (!ip) {
    return 0;
  }
 
  // Remove brackets if present
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ip, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate the normalized address
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // fc00::/7: Unique Local Addresses (ULA)
  // First byte should be 0xfc or 0xfd
  if ((addr.s6_addr[0] & 0xFE) == 0xFC) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv6(), and parse_ipv6_address().

Referenced by get_ip_type_string(), and is_internet_ipv6().

◆ is_link_local_ipv4()

int is_link_local_ipv4 ( const char * ip )

#include <ip.h>

Check if IPv4 address is a link-local address.

Parameters

ip	IPv4 address string (must not be NULL)

Returns: 1 if link-local, 0 otherwise

Checks if an IPv4 address is in the link-local range:

169.254.0.0/16 (169.254.0.0 - 169.254.255.255)

Link-local addresses are auto-configured when DHCP is unavailable (APIPA).

Note: Returns 0 for invalid IPv4 addresses.

Example: if (is_link_local_ipv4("169.254.1.1")) {

// This is an auto-configured link-local address

}

Definition at line 1356 of file ip.c.

                                       {
  if (!is_valid_ipv4(ip)) {
    return 0;
  }
 
  struct in_addr addr;
  if (inet_pton(AF_INET, ip, &addr) != 1) {
    return 0;
  }
 
  uint32_t ip_val = ntohl(addr.s_addr);
 
  // 169.254.0.0/16: Link-local addresses (APIPA)
  if ((ip_val & 0xFFFF0000) == 0xA9FE0000) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv4().

Referenced by is_internet_ipv4().

◆ is_link_local_ipv6()

int is_link_local_ipv6 ( const char * ip )

#include <ip.h>

Check if IPv6 address is a link-local address.

Parameters

ip	IPv6 address string (must not be NULL)

Returns: 1 if link-local, 0 otherwise

Checks if an IPv6 address is in the link-local range:

fe80::/10 (fe80:: - febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff)

Link-local addresses are auto-configured and only valid on a single link.

Note: Returns 0 for invalid IPv6 addresses.

Example: if (is_link_local_ipv6("fe80::1")) {

// This is a link-local address

}

Definition at line 1377 of file ip.c.

                                       {
  if (!ip) {
    return 0;
  }
 
  // Remove brackets if present
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ip, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate the normalized address
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // fe80::/10: Link-local addresses
  // First byte should be 0xfe, second byte & 0xc0 should be 0x80
  if (addr.s6_addr[0] == 0xFE && (addr.s6_addr[1] & 0xC0) == 0x80) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv6(), and parse_ipv6_address().

Referenced by is_internet_ipv6().

◆ is_localhost_ipv4()

int is_localhost_ipv4 ( const char * ip )

#include <ip.h>

Check if IPv4 address is localhost.

Parameters

ip	IPv4 address string (must not be NULL)

Returns: 1 if localhost, 0 otherwise

Checks if an IPv4 address is in the loopback range:

127.0.0.0/8 (127.0.0.0 - 127.255.255.255)

Note: Returns 0 for invalid IPv4 addresses.

Example: if (is_localhost_ipv4("127.0.0.1")) {

// This is a loopback address

}

Definition at line 1299 of file ip.c.

                                      {
  if (!is_valid_ipv4(ip)) {
    return 0;
  }
 
  struct in_addr addr;
  if (inet_pton(AF_INET, ip, &addr) != 1) {
    return 0;
  }
 
  uint32_t ip_val = ntohl(addr.s_addr);
 
  // 127.0.0.0/8: Loopback addresses
  if ((ip_val & 0xFF000000) == 0x7F000000) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv4().

Referenced by client_main(), get_ip_type_string(), is_internet_ipv4(), parse_server_bind_address(), and tcp_client_connect().

◆ is_localhost_ipv6()

int is_localhost_ipv6 ( const char * ip )

#include <ip.h>

Check if IPv6 address is localhost.

Parameters

ip	IPv6 address string (must not be NULL)

Returns: 1 if localhost, 0 otherwise

Checks if an IPv6 address is the loopback address:

::1

Note: Returns 0 for invalid IPv6 addresses.

Example: if (is_localhost_ipv6("::1")) {

// This is the IPv6 loopback address

}

Definition at line 1320 of file ip.c.

                                      {
  if (!ip) {
    return 0;
  }
 
  // Remove brackets if present
  char normalized[INET6_ADDRSTRLEN];
  if (parse_ipv6_address(ip, normalized, sizeof(normalized)) != 0) {
    return 0;
  }
 
  // Validate the normalized address
  if (!is_valid_ipv6(normalized)) {
    return 0;
  }
 
  struct in6_addr addr;
  if (inet_pton(AF_INET6, normalized, &addr) != 1) {
    return 0;
  }
 
  // ::1: Loopback address
  // All bytes should be 0 except the last byte which should be 1
  for (int i = 0; i < 15; i++) {
    if (addr.s6_addr[i] != 0) {
      return 0;
    }
  }
  if (addr.s6_addr[15] != 1) {
    return 0;
  }
 
  return 1;
}

References is_valid_ipv6(), and parse_ipv6_address().

Referenced by get_ip_type_string(), is_internet_ipv6(), parse_server_bind_address(), and tcp_client_connect().

◆ is_valid_ip()

int is_valid_ip ( const char * ip )

#include <ip.h>

Check if string is a valid IP address (IPv4 or IPv6)

Parameters

ip	String to validate (must not be NULL)

Returns: 1 if valid IPv4 or IPv6, 0 otherwise

Unified validation function that accepts either IPv4 or IPv6 addresses. Use this when you don't care about the IP version, just validity.

Note: IPv6 addresses can be with or without brackets.; Returns 0 for NULL, empty strings, or invalid addresses.

Example: if (is_valid_ip("192.168.1.1")) {

// Valid IPv4

}

if (is_valid_ip("::1")) {

// Valid IPv6

}

is_valid_ip
int is_valid_ip(const char *ip)
Check if string is a valid IP address (IPv4 or IPv6)
Definition ip.c:534

Definition at line 534 of file ip.c.

                                {
  if (!ip) {
    return 0;
  }
 
  // Try IPv4 first (faster check)
  if (is_valid_ipv4(ip)) {
    return 1;
  }
 
  // Try IPv6
  if (is_valid_ipv6(ip)) {
    return 1;
  }
 
  return 0;
}

References is_valid_ipv4(), and is_valid_ipv6().

◆ is_valid_ipv4()

int is_valid_ipv4 ( const char * ip )

#include <ip.h>

Check if a string is a valid IPv4 address.

Parameters

ip	String to validate (must not be NULL)

Returns: 1 if valid IPv4, 0 otherwise

Validates that a string is a valid IPv4 address in dotted decimal notation (e.g., "192.0.2.1"). Checks format correctness and numeric value ranges for each octet (0-255).

Note: Returns 0 for invalid format, out-of-range values, or non-IPv4 strings.; Does not validate that address is routable or assigned.

Example: if (is_valid_ipv4("192.0.2.1")) {

// Valid IPv4 address

}

Definition at line 58 of file ip.c.

                                  {
  if (!ip) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: NULL");
    return 0; // Invalid
  }
 
  size_t ip_len = strlen(ip);
  if (ip_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: empty string");
    return 0; // Invalid
  }
 
  if (ip_len > 256) {
    char ip_buffer[BUFFER_SIZE_SMALL];
    SAFE_STRNCPY(ip_buffer, ip, sizeof(ip_buffer));
    SET_ERRNO(ERROR_INVALID_PARAM, "Suspiciously long ip: %s", ip_buffer);
    return 0; // Invalid
  }
 
  // Get compiled IPv4 regex
  pcre2_code *regex = ipv4_regex_get();
  if (!regex) {
    log_error("IPv4 validator not initialized");
    return 0;
  }
 
  // Create match data for regex matching
  pcre2_match_data *match_data = pcre2_match_data_create_from_pattern(regex, NULL);
  if (!match_data) {
    log_error("Failed to allocate match data for IPv4 regex");
    return 0;
  }
 
  // Validate format using PCRE2 regex
  int match_result = pcre2_match(regex, (PCRE2_SPTR8)ip, ip_len, 0, 0, match_data, NULL);
 
  pcre2_match_data_free(match_data);
 
  if (match_result < 0) {
    return 0; // Format validation failed
  }
 
  return 1; // Valid IPv4 format
}

References BUFFER_SIZE_SMALL, ERROR_INVALID_PARAM, log_error, SAFE_STRNCPY, and SET_ERRNO.

Referenced by get_ip_version(), ipv4_to_ipv6_mapped(), is_broadcast_ipv4(), is_internet_ipv4(), is_lan_ipv4(), is_link_local_ipv4(), is_localhost_ipv4(), is_tailscale_host(), is_valid_ip(), parse_address_with_optional_port(), parse_client_address(), parse_server_bind_address(), and validate_opt_ip_address().

◆ is_valid_ipv6()

int is_valid_ipv6 ( const char * ip )

#include <ip.h>

Check if a string is a valid IPv6 address.

Parameters

ip	String to validate (with or without brackets, must not be NULL)

Returns: 1 if valid IPv6, 0 otherwise

Validates that a string is a valid IPv6 address. Accepts addresses with or without brackets (e.g., "::1" or "[::1]"). Checks format correctness including compressed zero notation (::) and valid hexadecimal groups.

Note: Returns 0 for invalid format, malformed addresses, or non-IPv6 strings.; Handles both bracketed and unbracketed IPv6 addresses.; Does not validate that address is routable or assigned.

Example: if (is_valid_ipv6("[::1]")) {

// Valid IPv6 address

}

Definition at line 105 of file ip.c.

                                  {
  if (!ip) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: NULL");
    return 0; // Invalid
  }
 
  size_t ip_len = strlen(ip);
  if (ip_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: empty string");
    return 0; // Invalid
  }
 
  if (ip_len > 256) {
    char ip_buffer[BUFFER_SIZE_SMALL];
    SAFE_STRNCPY(ip_buffer, ip, sizeof(ip_buffer));
    SET_ERRNO(ERROR_INVALID_PARAM, "Suspiciously long ip: %s", ip_buffer);
    return 0; // Invalid
  }
 
  // Remove brackets if present (IPv6 addresses can be bracketed)
  char normalized[INET6_ADDRSTRLEN];
  const char *ip_to_validate = ip;
 
  if (ip[0] == '[') {
    // Has brackets, need to remove them
    if (parse_ipv6_address(ip, normalized, sizeof(normalized)) != 0) {
      return 0; // Failed to parse (malformed brackets)
    }
    ip_to_validate = normalized;
  }
 
  // Use POSIX inet_pton() for robust IPv6 validation
  // It handles all RFC 5952 compliant formats:
  // - Full format: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
  // - Compressed: 2001:db8:85a3::8a2e:370:7334
  // - Loopback: ::1
  // - All zeros: ::
  // - IPv4-mapped: ::ffff:192.0.2.1
  struct in6_addr addr;
  int result = inet_pton(AF_INET6, ip_to_validate, &addr);
 
  if (result == 1) {
    return 1; // Valid IPv6
  } else if (result == 0) {
    return 0; // Not a valid IPv6 address
  } else {
    // result < 0 means system error (e.g., unsupported address family)
    SET_ERRNO(ERROR_INVALID_PARAM, "Failed to validate IPv6 address");
    return 0;
  }
}

References BUFFER_SIZE_SMALL, ERROR_INVALID_PARAM, parse_ipv6_address(), SAFE_STRNCPY, and SET_ERRNO.

Referenced by canonicalize_ipv6(), expand_ipv6(), get_ip_version(), is_anycast_ipv6(), is_broadcast_ipv6(), is_internet_ipv6(), is_ipv4_mapped_ipv6(), is_lan_ipv6(), is_link_local_ipv6(), is_localhost_ipv6(), is_tailscale_host(), is_valid_ip(), parse_address_with_optional_port(), parse_client_address(), parse_server_bind_address(), and validate_opt_ip_address().

◆ parse_address_with_optional_port()

int parse_address_with_optional_port	(	const char *	input,
		char *	address_output,
		size_t	address_output_size,
		uint16_t *	port_output,
		uint16_t	default_port
	)

#include <ip.h>

Parse address with optional port from string.

Parameters

input	Input string (address or address:port, must not be NULL)
address_output	Output buffer for address (without brackets, must not be NULL)
address_output_size	Size of address output buffer (must be > 0)
port_output	Pointer to store port number (must not be NULL)
default_port	Default port to use if not specified in input

Returns: 0 on success, -1 on error

Parses an address (IPv4, IPv6, or hostname) with an optional port number. If no port is specified, uses the default_port value. Handles various formats including bracketed IPv6 addresses.

SUPPORTED FORMATS (without port - uses default_port):

IPv4: "192.0.2.1"
IPv6: "::1" or "[::1]"
Hostname: "example.com" or "localhost"

SUPPORTED FORMATS (with port):

IPv4: "192.0.2.1:8080"
IPv6: "[2001:db8::1]:8080" (brackets required with port)
Hostname: "example.com:8080"

Note: IPv6 addresses with port MUST use brackets: "[::1]:8080"; IPv6 addresses without port can omit brackets: "::1" or "[::1]"; Port numbers are validated (1-65535 range).; Output address is normalized (brackets removed for IPv6).; Returns -1 on error (invalid format, buffer too small, invalid port, etc.).

Example: char addr[64];

uint16_t port;

// Without port - uses default

parse_address_with_optional_port("localhost", addr, sizeof(addr), &port, 27224);

// addr = "localhost", port = 27224

// With port

parse_address_with_optional_port("192.168.1.1:8080", addr, sizeof(addr), &port, 27224);

// addr = "192.168.1.1", port = 8080

// IPv6 without port

parse_address_with_optional_port("::1", addr, sizeof(addr), &port, 27224);

// addr = "::1", port = 27224

// IPv6 with port

parse_address_with_optional_port("[::1]:8080", addr, sizeof(addr), &port, 27224);

// addr = "::1", port = 8080

parse_address_with_optional_port
int parse_address_with_optional_port(const char *input, char *address_output, size_t address_output_size, uint16_t *port_output, uint16_t default_port)
Parse address with optional port from string.
Definition ip.c:370

Definition at line 370 of file ip.c.

                                                                                   {
  if (!input || !address_output || !port_output || address_output_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid arguments to parse_address_with_optional_port");
    return -1;
  }
 
  size_t input_len = strlen(input);
  if (input_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Empty address string");
    return -1;
  }
 
  if (input_len > 256) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Address string too long");
    return -1;
  }
 
  // Case 1: Bracketed IPv6 address with or without port
  // Examples: "[::1]" or "[::1]:8080" or "[2001:db8::1]:443"
  if (input[0] == '[') {
    const char *bracket_end = strchr(input, ']');
    if (!bracket_end) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Malformed bracketed address (missing ']'): %s", input);
      return -1;
    }
 
    // Extract address without brackets
    size_t addr_len = (size_t)(bracket_end - input - 1);
    if (addr_len == 0) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Empty bracketed address: %s", input);
      return -1;
    }
    if (addr_len >= address_output_size) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Address too long for buffer");
      return -1;
    }
 
    memcpy(address_output, input + 1, addr_len);
    address_output[addr_len] = '\0';
 
    // Validate it's a valid IPv6 address
    if (!is_valid_ipv6(address_output)) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IPv6 address: %s", address_output);
      return -1;
    }
 
    // Check for port after closing bracket
    if (bracket_end[1] == '\0') {
      // No port specified, use default
      *port_output = default_port;
    } else if (bracket_end[1] == ':') {
      // Port specified
      if (parse_port(bracket_end + 2, port_output) != ASCIICHAT_OK) {
        SET_ERRNO(ERROR_INVALID_PARAM, "Invalid port in: %s", input);
        return -1;
      }
    } else {
      SET_ERRNO(ERROR_INVALID_PARAM, "Invalid format after ']' (expected ':' or end): %s", input);
      return -1;
    }
    return 0;
  }
 
  // Case 2: Check if it's a valid IPv6 address without brackets (no port allowed in this case)
  // Examples: "::1" or "2001:db8::1" or "fe80::1"
  // Note: IPv6 addresses contain colons, so we can't use ':' as port separator without brackets
  if (is_valid_ipv6(input)) {
    if (strlen(input) >= address_output_size) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Address too long for buffer");
      return -1;
    }
    SAFE_STRNCPY(address_output, input, address_output_size);
    *port_output = default_port;
    return 0;
  }
 
  // Case 3: IPv4 or hostname, possibly with port
  // Examples: "192.168.1.1" or "192.168.1.1:8080" or "localhost" or "example.com:443"
  const char *last_colon = strrchr(input, ':');
 
  if (last_colon == NULL) {
    // No colon - just address/hostname, no port
    if (strlen(input) >= address_output_size) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Address too long for buffer");
      return -1;
    }
 
    // Validate it's a valid IPv4 or hostname
    if (!is_valid_ipv4(input) && !is_valid_hostname(input)) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Invalid address format: %s", input);
      return -1;
    }
 
    SAFE_STRNCPY(address_output, input, address_output_size);
    *port_output = default_port;
    return 0;
  }
 
  // Has colon - extract address and port
  size_t addr_len = (size_t)(last_colon - input);
  if (addr_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Empty address before port: %s", input);
    return -1;
  }
  if (addr_len >= address_output_size) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Address too long for buffer");
    return -1;
  }
 
  memcpy(address_output, input, addr_len);
  address_output[addr_len] = '\0';
 
  // Check if extracted address contains ':' - that would be IPv6 without brackets (invalid with port)
  if (strchr(address_output, ':') != NULL) {
    SET_ERRNO(ERROR_INVALID_PARAM, "IPv6 addresses must use brackets when specifying port: [%s]:%s instead of %s",
              address_output, last_colon + 1, input);
    return -1;
  }
 
  // Validate address part is valid IPv4 or hostname
  if (!is_valid_ipv4(address_output) && !is_valid_hostname(address_output)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid address format: %s", address_output);
    return -1;
  }
 
  // Parse port
  if (parse_port(last_colon + 1, port_output) != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid port in: %s", input);
    return -1;
  }
 
  return 0;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, is_valid_ipv4(), is_valid_ipv6(), parse_port(), SAFE_STRNCPY, and SET_ERRNO.

◆ parse_cidr()

int parse_cidr	(	const char *	cidr,
		char *	ip_out,
		size_t	ip_out_size,
		int *	prefix_out
	)

#include <ip.h>

Parse CIDR notation into IP and prefix length.

Parameters

cidr	CIDR string (e.g., "192.168.1.0/24", must not be NULL)
ip_out	Output buffer for IP address (without prefix, must not be NULL)
ip_out_size	Size of IP output buffer
prefix_out	Pointer to store prefix length (must not be NULL)

Returns: 0 on success, -1 on error

Parses CIDR notation into separate IP address and prefix length components. Supports both IPv4 and IPv6 CIDR notation.

SUPPORTED FORMATS:

IPv4: "192.168.1.0/24" -> ip="192.168.1.0", prefix=24
IPv6: "2001:db8::/32" -> ip="2001:db8::", prefix=32
IPv6 with brackets: "[::1]/128" -> ip="::1", prefix=128

Note: Validates that prefix length is in valid range (0-32 for IPv4, 0-128 for IPv6).; Output IP has brackets removed for IPv6.; Returns -1 on error (invalid format, out of range prefix, buffer too small).

Example: char ip[64];

int prefix;

if (parse_cidr("192.168.1.0/24", ip, sizeof(ip), &prefix) == 0) {

// ip = "192.168.1.0", prefix = 24

}

Definition at line 665 of file ip.c.

                                                                                    {
  if (!cidr || !ip_out || !prefix_out || ip_out_size == 0) {
    return -1;
  }
 
  // Find the '/' separator
  const char *slash = strchr(cidr, '/');
  if (!slash) {
    return -1; // No slash found
  }
 
  // Extract IP part
  size_t ip_len = (size_t)(slash - cidr);
  if (ip_len == 0 || ip_len >= ip_out_size) {
    return -1;
  }
 
  char ip_temp[256];
  if (ip_len >= sizeof(ip_temp)) {
    return -1;
  }
 
  memcpy(ip_temp, cidr, ip_len);
  ip_temp[ip_len] = '\0';
 
  // Remove brackets if IPv6
  if (ip_temp[0] == '[') {
    if (parse_ipv6_address(ip_temp, ip_out, ip_out_size) != 0) {
      return -1;
    }
  } else {
    if (ip_len >= ip_out_size) {
      return -1;
    }
    memcpy(ip_out, ip_temp, ip_len + 1);
  }
 
  // Validate IP
  int version = get_ip_version(ip_out);
  if (version == 0) {
    return -1; // Invalid IP
  }
 
  // Parse prefix length
  const char *prefix_str = slash + 1;
  if (strlen(prefix_str) == 0) {
    return -1;
  }
 
  char *endptr;
  long prefix = strtol(prefix_str, &endptr, 10);
  if (*endptr != '\0' || prefix < 0) {
    return -1; // Invalid prefix
  }
 
  // Validate prefix range based on IP version
  if (version == 4 && (prefix > 32)) {
    return -1;
  }
  if (version == 6 && (prefix > 128)) {
    return -1;
  }
 
  *prefix_out = (int)prefix;
  return 0;
}

References get_ip_version(), and parse_ipv6_address().

Referenced by ip_in_cidr().

◆ parse_ip_with_port()

int parse_ip_with_port	(	const char *	input,
		char *	ip_output,
		size_t	ip_output_size,
		uint16_t *	port_output
	)

#include <ip.h>

Parse IP address and port from string.

Parameters

input	Input string with port (must not be NULL, format: "ip:port" or "[ip]:port")
ip_output	Output buffer for IP address (without brackets, must not be NULL)
ip_output_size	Size of IP output buffer (must be > 0)
port_output	Pointer to store port number (must not be NULL)

Returns: 0 on success, -1 on error

Parses an IP address (IPv4 or IPv6) with port number from a string. Handles various formats including bracketed IPv6 addresses. Also accepts hostnames (non-IP addresses).

SUPPORTED FORMATS:

IPv4: "192.0.2.1:8080"
IPv6: "[2001:db8::1]:8080"
Hostname: "example.com:8080"

Note: IPv6 addresses must use brackets in input format.; Port numbers are validated (0-65535 range).; Output IP address is normalized (brackets removed).; Returns -1 on error (invalid format, buffer too small, invalid port, etc.).

Example: char ip[64];

uint16_t port;

if (parse_ip_with_port("[::1]:8080", ip, sizeof(ip), &port) == 0) {

// ip = "::1", port = 8080

}

Definition at line 296 of file ip.c.

                                                                                                         {
  if (!input || !ip_output || !port_output || ip_output_size == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: %s", input);
    return -1;
  }
 
  if (strlen(input) == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid IP format: %s", input);
    return -1;
  }
 
  if (strlen(input) > 256) {
    char input_buffer[BUFFER_SIZE_SMALL];
    SAFE_STRNCPY(input_buffer, input, sizeof(input_buffer));
    SET_ERRNO(ERROR_INVALID_PARAM, "Suspiciously long ip: %s", input_buffer);
    return -1;
  }
 
  // Check for IPv6 bracket notation: [2001:db8::1]:8080
  if (input[0] == '[') {
    // Find closing bracket
    const char *bracket_end = strchr(input, ']');
    if (!bracket_end)
      return -1; // Malformed - opening bracket but no closing bracket
 
    // Extract IP address (without brackets)
    size_t ip_len = (size_t)(bracket_end - input - 1);
    if (ip_len >= ip_output_size)
      return -1; // IP too long
 
    memcpy(ip_output, input + 1, ip_len);
    ip_output[ip_len] = '\0';
 
    // Check for port after closing bracket
    if (bracket_end[1] == ':') {
      // Parse port using safe integer parsing
      if (parse_port(bracket_end + 2, port_output) != ASCIICHAT_OK) {
        return -1; // Invalid port
      }
    } else {
      return -1; // Expected ':' after closing bracket
    }
  } else {
    // IPv4 or hostname: "192.0.2.1:8080" or "example.com:8080"
    // Find last ':' for port separation
    const char *colon = strrchr(input, ':');
    if (!colon)
      return -1; // No port separator
 
    // Extract IP/hostname
    size_t ip_len = (size_t)(colon - input);
    if (ip_len >= ip_output_size)
      return -1; // IP too long
 
    memcpy(ip_output, input, ip_len);
    ip_output[ip_len] = '\0';
 
    // Reject IPv6 without brackets (check if extracted IP contains ':')
    // This catches cases like "::1:8080" which should be "[::1]:8080"
    if (strchr(ip_output, ':') != NULL)
      return -1; // IPv6 address without brackets - invalid format
 
    // Parse port using safe integer parsing
    if (parse_port(colon + 1, port_output) != ASCIICHAT_OK) {
      return -1; // Invalid port
    }
  }
 
  return 0;
}

References ASCIICHAT_OK, BUFFER_SIZE_SMALL, ERROR_INVALID_PARAM, parse_port(), SAFE_STRNCPY, and SET_ERRNO.

Referenced by compare_ip_port_strings().

◆ parse_ipv6_address()

int parse_ipv6_address	(	const char *	input,
		char *	output,
		size_t	output_size
	)

#include <ip.h>

Parse IPv6 address, removing brackets if present.

Parameters

input	Input address (may have brackets, must not be NULL)
output	Output buffer for parsed address (without brackets, must not be NULL)
output_size	Size of output buffer (must be > 0)

Returns: 0 on success, -1 on error

Parses an IPv6 address and removes brackets if present. Handles both bracketed and unbracketed formats. Validates the address and normalizes it to unbracketed form for internal use.

SUPPORTED FORMATS:

"::1" -> "::1"
"[::1]" -> "::1"
"2001:db8::1" -> "2001:db8::1"
"[2001:db8::1]" -> "2001:db8::1"

Note: Output buffer must be large enough to hold IPv6 address (at least 39 bytes).; Returns -1 on error (invalid address, buffer too small, etc.).; Brackets are removed from output (address is normalized).

Definition at line 158 of file ip.c.

                                                                            {
  if (!input || !output || output_size == 0)
    return -1;
 
  size_t input_len = strlen(input);
  if (input_len == 0)
    return -1; // Empty string
 
  const char *start = input;
  const char *end = input + input_len;
 
  // Remove brackets if present - but brackets must be matched
  if (*start == '[') {
    if (input_len < 2 || *(end - 1) != ']')
      return -1; // Malformed brackets
    start++;
    end--;
 
    // Check for double brackets [[...]]
    if (start < end && *start == '[')
      return -1; // Double opening bracket
  } else if (*(end - 1) == ']') {
    // Closing bracket without opening bracket
    return -1;
  }
 
  size_t len = (size_t)(end - start);
  if (len == 0)
    return -1; // Empty content after removing brackets
  if (len >= output_size)
    return -1; // Buffer too small
 
  memcpy(output, start, len);
  output[len] = '\0';
  return 0;
}

Referenced by canonicalize_ipv6(), expand_ipv6(), extract_ipv4_from_mapped_ipv6(), ip_compare(), ip_equals(), ip_in_cidr_parsed(), is_anycast_ipv6(), is_broadcast_ipv6(), is_internet_ipv6(), is_ipv4_mapped_ipv6(), is_lan_ipv6(), is_link_local_ipv6(), is_localhost_ipv6(), is_valid_ipv6(), parse_cidr(), parse_server_bind_address(), and validate_opt_ip_address().

◆ path_cleanup_thread_locals()

void path_cleanup_thread_locals ( void )

#include <path.h>

Cleanup thread-local path resources.

Frees PCRE2 match data allocated for thread-local path normalization. Called automatically on thread exit. Safe to call multiple times.

Note: This is called automatically by the threading system - users should not need to call this directly.

Cleanup thread-local PCRE2 resources (now a no-op, kept for compatibility)

Previously this freed cached thread-local match data, but we now allocate fresh match data for each operation and free it immediately, so there's nothing to clean up. This function is kept for API compatibility.

Definition at line 85 of file path.c.

                                      {
  /* No-op: match data is now allocated and freed immediately per operation */
}

Referenced by main().

◆ path_is_absolute()

bool path_is_absolute ( const char * path )

#include <path.h>

Determine whether a path is absolute on the current platform.

Parameters

path	Path string to test (may be NULL)

Returns: true if the path is absolute, false otherwise

Definition at line 739 of file path.c.

                                        {
  if (!path || !*path) {
    return false;
  }
 
#ifdef _WIN32
  if ((path[0] == '\\' && path[1] == '\\')) {
    return true; // UNC path
  }
  if (isalpha((unsigned char)path[0]) && path[1] == PATH_DRIVE_SEPARATOR && path[2] == PATH_DELIM) {
    return true;
  }
  return false;
#else
  return path[0] == PATH_DELIM;
#endif
}

References PATH_DELIM, and PATH_DRIVE_SEPARATOR.

Referenced by path_is_within_base(), and path_validate_user_path().

◆ path_is_within_any_base()

bool path_is_within_any_base	(	const char *	path,
		const char const	bases,
		size_t	base_count
	)

#include <path.h>

Check whether a path resides within any of several base directories.

Parameters

path	Candidate path to validate (must be absolute)
bases	Array of base directory strings
base_count	Number of entries in `bases`

Returns: true if path is inside any allowed base, false otherwise

Definition at line 791 of file path.c.

                                                                                            {
  if (!path || !bases || base_count == 0) {
    return false;
  }
 
  for (size_t i = 0; i < base_count; ++i) {
    const char *base = bases[i];
    if (!base) {
      continue;
    }
    if (path_is_within_base(path, base)) {
      return true;
    }
  }
 
  return false;
}

References path_is_within_base().

Referenced by path_validate_user_path().

◆ path_is_within_base()

bool path_is_within_base	(	const char *	path,
		const char *	base
	)

#include <path.h>

Check whether a path resides within a specified base directory.

Both the candidate path and the base directory are normalized before comparison. The base directory must be absolute. The comparison honours the platform's case sensitivity rules (case-insensitive on Windows).

Parameters

path	Candidate path to validate (must be absolute)
base	Absolute base directory to compare against

Returns: true if path is inside base (or exactly equal), false otherwise

Definition at line 757 of file path.c.

                                                             {
  if (!path || !base) {
    return false;
  }
 
  if (!path_is_absolute(path) || !path_is_absolute(base)) {
    return false;
  }
 
  char normalized_path[PLATFORM_MAX_PATH_LENGTH];
  char normalized_base[PLATFORM_MAX_PATH_LENGTH];
 
  if (!path_normalize_copy(path, normalized_path, sizeof(normalized_path))) {
    return false;
  }
  if (!path_normalize_copy(base, normalized_base, sizeof(normalized_base))) {
    return false;
  }
 
  size_t base_len = strlen(normalized_base);
  if (base_len == 0) {
    return false;
  }
 
  if (platform_path_strcasecmp(normalized_path, normalized_base, base_len) != 0) {
    return false;
  }
  char next = normalized_path[base_len];
  if (next == '\0') {
    return true;
  }
  return next == PATH_DELIM;
}

References PATH_DELIM, path_is_absolute(), path_normalize_copy(), PLATFORM_MAX_PATH_LENGTH, and platform_path_strcasecmp().

Referenced by path_is_within_any_base().

◆ path_looks_like_path()

bool path_looks_like_path ( const char * value )

#include <path.h>

Determine if a string is likely intended to reference the filesystem.

Heuristics include presence of path separators, leading ~, relative prefixes, or Windows drive designators. Used to avoid treating tokens like "github:user" or raw hex keys as file paths.

Parameters

value String to analyze

Returns: true if the string looks like a filesystem path

Definition at line 809 of file path.c.

                                             {
  if (!value || *value == '\0') {
    return false;
  }
 
  if (value[0] == PATH_DELIM || value[0] == PATH_COMPONENT_DOT || value[0] == PATH_TILDE) {
    return true;
  }
 
  if (strchr(value, PATH_DELIM)) {
    return true;
  }
 
#ifdef _WIN32
  if (isalpha((unsigned char)value[0]) && value[1] == ':' && value[2] == PATH_DELIM) {
    return true;
  }
#endif
 
  return false;
}

References PATH_COMPONENT_DOT, PATH_DELIM, and PATH_TILDE.

Referenced by options_init(), parse_keys_from_file(), parse_public_key(), parse_public_keys(), path_validate_user_path(), and validate_ssh_key_file().

◆ path_normalize_copy()

bool path_normalize_copy	(	const char *	path,
		char *	out,
		size_t	out_len
	)

#include <path.h>

Normalize a path and copy it into the provided buffer.

Resolves '.' and '..' components without requiring the path to exist on disk. The output buffer receives a canonicalized representation using platform preferred separators.

Parameters

path	Input path string (must not be NULL)
out	Destination buffer for normalized path
out_len	Size of destination buffer in bytes

Returns: true on success, false on failure (invalid arguments or buffer too small)

Definition at line 719 of file path.c.

                                                                      {
  if (!path || !out || out_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null path or out or out_len is 0");
    return false;
  }
 
  const char *normalized = normalize_path(path);
  if (!normalized) {
    return false;
  }
 
  size_t len = strlen(normalized);
  if (len + 1 > out_len) {
    return false;
  }
 
  memcpy(out, normalized, len + 1);
  return true;
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by path_is_within_base(), and path_validate_user_path().

◆ path_validate_user_path()

asciichat_error_t path_validate_user_path	(	const char *	input,
		path_role_t	role,
		char **	normalized_out
	)

#include <path.h>

Validate and canonicalize a user-supplied filesystem path.

Resolves ~, relative segments, and enforces that the resulting absolute path resides within the trusted base directories for the supplied role.

Trusted base directories include:

Current working directory
System temp directory
User config directory (~/.ascii-chat/ or APPDATA%\ascii-chat)
User home directory
User SSH directory (~/.ssh/)
System config directories (Unix: /etc/ascii-chat/, /usr/local/etc/ascii-chat/)
System log directories (Unix: /var/log/, /var/tmp/)
System-wide app data (Windows: PROGRAMDATA%\ascii-chat)

Note: For PATH_ROLE_LOG_FILE, the base directory check is skipped to allow logging to any writable location.

Parameters

input	Original user-provided path (must not be NULL)
role	Intended usage category
normalized_out	Output pointer receiving SAFE_MALLOC'd canonical path

Returns: ASCIICHAT_OK on success, error code on failure (and normalized_out is NULL)

Definition at line 1020 of file path.c.

                                                                                                      {
  if (!normalized_out) {
    return SET_ERRNO(map_role_to_error(role), "path_validate_user_path requires output pointer");
  }
  *normalized_out = NULL;
 
  if (!input || *input == '\0') {
    return SET_ERRNO(map_role_to_error(role), "Path is empty for role %d", role);
  }
 
  // SECURITY: For log files, if input is a simple filename (no separators or ..), constrain it to a safe directory
  if (role == PATH_ROLE_LOG_FILE) {
    // Check if input contains path separators or parent directory references
    bool is_simple_filename = true;
    for (const char *p = input; *p; p++) {
      if (*p == PATH_DELIM || *p == '/' || *p == '\\') {
        is_simple_filename = false;
        break;
      }
    }
    // Also reject ".." components (even without separators like "..something")
    if (strstr(input, "..") != NULL) {
      is_simple_filename = false;
    }
 
    // If it's a simple filename, resolve it to a safe base directory
    if (is_simple_filename) {
      // Always prefer current working directory for simple log filenames
      // This ensures logs go to where the user is running the command from
      char safe_base[PLATFORM_MAX_PATH_LENGTH];
 
      if (!platform_get_cwd(safe_base, sizeof(safe_base))) {
        // If cwd fails, try config dir as fallback
        char *config_dir = get_config_dir();
        if (config_dir) {
          SAFE_STRNCPY(safe_base, config_dir, sizeof(safe_base));
          SAFE_FREE(config_dir);
        } else {
          return SET_ERRNO(ERROR_LOGGING_INIT, "Failed to determine safe directory for log file");
        }
      }
 
      // Build the full path: safe_base + separator + input
      size_t base_len = strlen(safe_base);
      size_t input_len = strlen(input);
      bool needs_sep = base_len > 0 && safe_base[base_len - 1] != PATH_DELIM;
      size_t total_len = base_len + (needs_sep ? 1 : 0) + input_len + 1;
 
      if (total_len > PLATFORM_MAX_PATH_LENGTH) {
        return SET_ERRNO(ERROR_LOGGING_INIT, "Log file path too long: %s/%s", safe_base, input);
      }
 
      char resolved_buf[PLATFORM_MAX_PATH_LENGTH];
      safe_snprintf(resolved_buf, sizeof(resolved_buf), "%s%s%s", safe_base, needs_sep ? PATH_SEPARATOR_STR : "",
                    input);
 
      // Normalize the resolved path
      char normalized_buf[PLATFORM_MAX_PATH_LENGTH];
      if (!path_normalize_copy(resolved_buf, normalized_buf, sizeof(normalized_buf))) {
        return SET_ERRNO(ERROR_LOGGING_INIT, "Failed to normalize log file path: %s", resolved_buf);
      }
 
      // Allocate and return the result
      char *result = SAFE_MALLOC(strlen(normalized_buf) + 1, char *);
      if (!result) {
        return SET_ERRNO(ERROR_MEMORY, "Failed to allocate normalized path");
      }
      safe_snprintf(result, strlen(normalized_buf) + 1, "%s", normalized_buf);
      *normalized_out = result;
      return ASCIICHAT_OK;
    }
    // If not a simple filename (contains separators), continue with normal validation below
  }
 
  // For non-log-files or log files with path separators, validate as usual
  if (role != PATH_ROLE_LOG_FILE && !path_looks_like_path(input)) {
    return SET_ERRNO(map_role_to_error(role), "Value does not look like a filesystem path: %s", input);
  }
 
  char *expanded = expand_path(input);
  if (!expanded) {
    return SET_ERRNO(map_role_to_error(role), "Failed to expand path: %s", input);
  }
 
  char candidate_buf[PLATFORM_MAX_PATH_LENGTH];
  const char *candidate_path = expanded;
 
  if (!path_is_absolute(candidate_path)) {
    char cwd_buf[PLATFORM_MAX_PATH_LENGTH];
    if (!platform_get_cwd(cwd_buf, sizeof(cwd_buf))) {
      SAFE_FREE(expanded);
      return SET_ERRNO(map_role_to_error(role), "Failed to determine current working directory");
    }
 
    size_t total_len = strlen(cwd_buf) + 1 + strlen(candidate_path) + 1;
    if (total_len >= sizeof(candidate_buf)) {
      SAFE_FREE(expanded);
      return SET_ERRNO(map_role_to_error(role), "Resolved path is too long: %s/%s", cwd_buf, candidate_path);
    }
    if (strlen(candidate_path) > 0 && candidate_path[0] == PATH_DELIM) {
      safe_snprintf(candidate_buf, sizeof(candidate_buf), "%s%s", cwd_buf, candidate_path);
    } else {
      safe_snprintf(candidate_buf, sizeof(candidate_buf), "%s%c%s", cwd_buf, PATH_DELIM, candidate_path);
    }
    candidate_path = candidate_buf;
  }
 
  char normalized_buf[PLATFORM_MAX_PATH_LENGTH];
  if (!path_normalize_copy(candidate_path, normalized_buf, sizeof(normalized_buf))) {
    SAFE_FREE(expanded);
    return SET_ERRNO(map_role_to_error(role), "Failed to normalize path: %s", candidate_path);
  }
 
  if (!path_is_absolute(normalized_buf)) {
    SAFE_FREE(expanded);
    return SET_ERRNO(map_role_to_error(role), "Normalized path is not absolute: %s", normalized_buf);
  }
 
  const char *bases[MAX_PATH_BASES] = {0};
  size_t base_count = 0;
 
  // Always add current working directory as an allowed base
  // This is critical for log files and other paths relative to where the user runs the command
  char cwd_base[PLATFORM_MAX_PATH_LENGTH];
  if (platform_get_cwd(cwd_base, sizeof(cwd_base))) {
    append_base_if_valid(cwd_base, bases, &base_count);
  }
 
  char temp_base[PLATFORM_MAX_PATH_LENGTH];
  if (platform_get_temp_dir(temp_base, sizeof(temp_base))) {
    append_base_if_valid(temp_base, bases, &base_count);
  }
 
  char *config_dir = get_config_dir();
  if (config_dir) {
    append_base_if_valid(config_dir, bases, &base_count);
  }
 
  const char *home_env = platform_get_home_dir();
  if (home_env) {
    append_base_if_valid(home_env, bases, &base_count);
  }
 
  char ascii_chat_home[PLATFORM_MAX_PATH_LENGTH];
  if (home_env) {
    build_ascii_chat_path(home_env, ".ascii-chat", ascii_chat_home, sizeof(ascii_chat_home));
    append_base_if_valid(ascii_chat_home, bases, &base_count);
  }
 
#ifndef _WIN32
  char ascii_chat_home_tmp[PLATFORM_MAX_PATH_LENGTH];
  build_ascii_chat_path("/tmp", ".ascii-chat", ascii_chat_home_tmp, sizeof(ascii_chat_home_tmp));
  append_base_if_valid(ascii_chat_home_tmp, bases, &base_count);
#endif
 
  char ssh_home[PLATFORM_MAX_PATH_LENGTH];
  if (home_env) {
    build_ascii_chat_path(home_env, ".ssh", ssh_home, sizeof(ssh_home));
    append_base_if_valid(ssh_home, bases, &base_count);
  }
 
#ifdef _WIN32
  char program_data_logs[PLATFORM_MAX_PATH_LENGTH];
  const char *program_data = platform_getenv("PROGRAMDATA");
  if (program_data) {
    build_ascii_chat_path(program_data, "ascii-chat", program_data_logs, sizeof(program_data_logs));
    append_base_if_valid(program_data_logs, bases, &base_count);
  }
#else
  // System-wide config directories (for server deployments)
  append_base_if_valid("/etc/ascii-chat", bases, &base_count);
  append_base_if_valid("/usr/local/etc/ascii-chat", bases, &base_count);
  append_base_if_valid("/var/log", bases, &base_count);
  append_base_if_valid("/var/tmp", bases, &base_count);
  append_base_if_valid("/tmp", bases, &base_count);
#ifdef __APPLE__
  // On macOS, /tmp is a symlink to /private/tmp
  append_base_if_valid("/private/tmp", bases, &base_count);
  // On macOS, all user home directories are under /Users
  append_base_if_valid("/Users", bases, &base_count);
#endif
#endif
 
  // Security check: Reject paths that point to sensitive system files
  // This applies to all path roles, not just logs
  if (is_sensitive_system_path(normalized_buf)) {
    SAFE_FREE(expanded);
    if (config_dir) {
      SAFE_FREE(config_dir);
    }
    return SET_ERRNO(map_role_to_error(role), "Cannot write to protected system path: %s", normalized_buf);
  }
 
  // For log files, apply special validation rules
  if (role == PATH_ROLE_LOG_FILE) {
    // Check if path is a regular file (not a directory, not non-existent)
    // On macOS, fopen() can succeed on directories, so we must use platform_is_regular_file()
    bool is_regular_file = platform_is_regular_file(normalized_buf);
 
    // If a regular file exists, it MUST be an ascii-chat log or empty file to be overwritten
    if (is_regular_file && !is_existing_ascii_chat_log(normalized_buf) && !is_file_empty(normalized_buf)) {
      SAFE_FREE(expanded);
      if (config_dir) {
        SAFE_FREE(config_dir);
      }
      return SET_ERRNO(ERROR_LOGGING_INIT,
                       "Cannot overwrite existing non-ascii-chat file: %s\n"
                       "For safety, ascii-chat will only overwrite its own log files or empty files",
                       normalized_buf);
    }
 
    // If file doesn't exist (or is a directory), check that path is in safe locations
    if (!is_regular_file) {
      bool allowed = base_count == 0 ? true : path_is_within_any_base(normalized_buf, bases, base_count);
      if (!allowed) {
        SAFE_FREE(expanded);
        if (config_dir) {
          SAFE_FREE(config_dir);
        }
        return SET_ERRNO(ERROR_LOGGING_INIT,
                         "Log path %s is outside allowed directories (use -L /tmp/file.log, ~/file.log, or "
                         "relative/absolute paths in safe locations)",
                         normalized_buf);
      }
    }
  } else {
    // For non-log-file paths, apply standard whitelist validation
    bool allowed = base_count == 0 ? true : path_is_within_any_base(normalized_buf, bases, base_count);
    if (!allowed) {
      SAFE_FREE(expanded);
      if (config_dir) {
        SAFE_FREE(config_dir);
      }
      return SET_ERRNO(map_role_to_error(role), "Path %s is outside allowed directories", normalized_buf);
    }
  }
 
  char *result = SAFE_MALLOC(strlen(normalized_buf) + 1, char *);
  if (!result) {
    SAFE_FREE(expanded);
    if (config_dir) {
      SAFE_FREE(config_dir);
    }
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate normalized path");
  }
  safe_snprintf(result, strlen(normalized_buf) + 1, "%s", normalized_buf);
  *normalized_out = result;
 
  SAFE_FREE(expanded);
  if (config_dir) {
    SAFE_FREE(config_dir);
  }
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_LOGGING_INIT, ERROR_MEMORY, expand_path(), get_config_dir(), MAX_PATH_BASES, PATH_DELIM, path_is_absolute(), path_is_within_any_base(), path_looks_like_path(), path_normalize_copy(), PATH_ROLE_LOG_FILE, PATH_SEPARATOR_STR, platform_get_cwd(), platform_get_home_dir(), platform_get_temp_dir(), platform_getenv(), platform_is_regular_file(), PLATFORM_MAX_PATH_LENGTH, SAFE_FREE, SAFE_MALLOC, safe_snprintf(), SAFE_STRNCPY, SET_ERRNO, and true.

Referenced by config_create_default(), config_load_and_apply(), parse_keys_from_file(), parse_log_file(), parse_private_key(), parse_public_key(), and validate_ssh_key_file().

◆ prompt_password()

int prompt_password	(	const char *	prompt,
		char *	password,
		size_t	max_len
	)

#include <password.h>

Prompt the user for a password with secure input.

Parameters

prompt	The prompt message to display
password	Buffer to store the entered password
max_len	Maximum length of the password buffer (including null terminator)

Returns: 0 on success, -1 on failure or user cancellation

Displays a formatted password prompt with visual separators:

========================================
<prompt>
========================================
> ********
========================================

Input is masked with asterisks and echo is disabled for security.

Note: Returns -1 if stdin is not a TTY (non-interactive mode).; Acquires terminal lock during prompting.

Definition at line 72 of file lib/platform/wasm/stubs/crypto.c.

                                                                                                        {
  // Password prompts not supported in WASM
  return SET_ERRNO(ERROR_NOT_SUPPORTED, "Password prompts not supported in WASM");
}

References BUFFER_SIZE_SMALL, ERROR_NOT_SUPPORTED, log_lock_terminal(), log_plain, log_unlock_terminal(), log_warn, platform_is_interactive(), platform_prompt_question(), PROMPT_OPTS_PASSWORD, SET_ERRNO, utf8_display_width(), and utf8_is_valid().

Referenced by crypto_handshake_client_auth_response().

◆ prompt_password_simple()

int prompt_password_simple	(	const char *	prompt,
		char *	password,
		size_t	max_len
	)

#include <password.h>

Prompt the user for a password with simple formatting.

Parameters

prompt	The prompt message to display (shown inline)
password	Buffer to store the entered password
max_len	Maximum length of the password buffer (including null terminator)

Returns: 0 on success, -1 on failure or user cancellation

Displays a simple inline password prompt:

<prompt>: ********

Use this for simpler prompts like SSH key passphrases.

Note: Returns -1 if stdin is not a TTY (non-interactive mode).; Acquires terminal lock during prompting.

Definition at line 70 of file password.c.

                                                                               {
  if (!prompt || !password || max_len < 2) {
    return -1;
  }
 
  // Check for non-interactive mode first
  if (!platform_is_interactive()) {
    return -1;
  }
 
  // Build prompt with colon suffix, using byte-length for memcpy
  char full_prompt[BUFFER_SIZE_SMALL];
  size_t prompt_byte_len = strlen(prompt);
  if (prompt_byte_len >= sizeof(full_prompt) - 2) {
    prompt_byte_len = sizeof(full_prompt) - 3;
  }
  memcpy(full_prompt, prompt, prompt_byte_len);
  full_prompt[prompt_byte_len] = ':';
  full_prompt[prompt_byte_len + 1] = '\0';
 
  // Prompt for password with asterisk masking, same line
  prompt_opts_t opts = PROMPT_OPTS_PASSWORD;
  int result = platform_prompt_question(full_prompt, password, max_len, opts);
 
  // Validate password is valid UTF-8 (should always succeed since platform_prompt_question handles it)
  if (result == 0 && !utf8_is_valid(password)) {
    log_warn("Password contains invalid UTF-8 sequence, input may be corrupted");
  }
 
  return result;
}

References BUFFER_SIZE_SMALL, log_warn, platform_is_interactive(), platform_prompt_question(), PROMPT_OPTS_PASSWORD, and utf8_is_valid().

Referenced by parse_ssh_private_key(), and read_password_from_stdin().

◆ safe_parse_audio_message()

asciichat_error_t safe_parse_audio_message	(	const char *	message,
		unsigned int *	num_samples
	)

#include <parsing.h>

Parse AUDIO message format.

Parameters

message	Input message string (must not be NULL, format: "AUDIO:num_samples")
num_samples	Output parameter for parsed sample count (must not be NULL)

Returns: ASCIICHAT_OK on success, error code on failure

Parses an AUDIO protocol message in the format "AUDIO:num_samples" where num_samples is an unsigned integer. Validates the message format, parses the numeric value, and checks for overflow conditions.

MESSAGE FORMAT:

Must start with "AUDIO:"
Sample count must be a valid unsigned integer
No whitespace allowed in value

Note: num_samples is only modified on successful parsing.; Returns ASCIICHAT_ERROR_INVALID_ARGUMENT if format is invalid.; Returns ASCIICHAT_ERROR_OVERFLOW if numeric value exceeds limits.

Example: unsigned int num_samples;

if (safe_parse_audio_message("AUDIO:44100", &num_samples) == ASCIICHAT_OK) {

// num_samples = 44100

}

safe_parse_audio_message
asciichat_error_t safe_parse_audio_message(const char *message, unsigned int *num_samples)
Parse AUDIO message format.
Definition util/parsing.c:64

Definition at line 64 of file util/parsing.c.

                                                                                           {
  if (!message || !num_samples) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for audio message parsing");
  }
 
  // Check if message starts with "AUDIO:"
  if (strncmp(message, "AUDIO:", 6) != 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Message does not start with 'AUDIO:'");
  }
 
  const char *ptr = message + 6; // Skip "AUDIO:"
  char *endptr;
 
  // Parse number
  errno = 0;
  unsigned long samples = strtoul(ptr, &endptr, 10);
  if (errno != 0 || endptr == ptr || samples > UINT_MAX || samples == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid sample count value in audio message");
  }
 
  // Should end with newline or null terminator
  if (*endptr != '\n' && *endptr != '\0') {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid format: audio message should end with newline or null terminator");
  }
 
  *num_samples = (unsigned int)samples;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, errno, ERROR_INVALID_PARAM, and SET_ERRNO.

◆ safe_parse_size_message()

asciichat_error_t safe_parse_size_message	(	const char *	message,
		unsigned int *	width,
		unsigned int *	height
	)

#include <parsing.h>

Parse SIZE message format.

Parameters

message	Input message string (must not be NULL, format: "SIZE:width,height")
width	Output parameter for parsed width (must not be NULL)
height	Output parameter for parsed height (must not be NULL)

Returns: ASCIICHAT_OK on success, error code on failure

Parses a SIZE protocol message in the format "SIZE:width,height" where width and height are unsigned integers. Validates the message format, parses numeric values, and checks for overflow conditions.

MESSAGE FORMAT:

Must start with "SIZE:"
Width and height separated by comma
Both values must be valid unsigned integers
No whitespace allowed in values

Note: Width and height are only modified on successful parsing.; Returns ASCIICHAT_ERROR_INVALID_ARGUMENT if format is invalid.; Returns ASCIICHAT_ERROR_OVERFLOW if numeric values exceed limits.

Example: unsigned int width, height;

if (safe_parse_size_message("SIZE:1920,1080", &width, &height) == ASCIICHAT_OK) {

// width = 1920, height = 1080

}

safe_parse_size_message
asciichat_error_t safe_parse_size_message(const char *message, unsigned int *width, unsigned int *height)
Parse SIZE message format.
Definition util/parsing.c:16

Definition at line 16 of file util/parsing.c.

                                                                                                          {
  if (!message || !width || !height) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for size message parsing");
  }
 
  // Check if message starts with "SIZE:"
  if (strncmp(message, "SIZE:", 5) != 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Message does not start with 'SIZE:'");
  }
 
  const char *ptr = message + 5; // Skip "SIZE:"
  char *endptr;
 
  // Parse first number (width)
  errno = 0;
  unsigned long w = strtoul(ptr, &endptr, 10);
  if (errno != 0 || endptr == ptr || w > UINT_MAX || w == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid width value in size message");
  }
 
  // Check for comma separator
  if (*endptr != ',') {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing comma separator in size message");
  }
  ptr = endptr + 1;
 
  // Parse second number (height)
  errno = 0;
  unsigned long h = strtoul(ptr, &endptr, 10);
  if (errno != 0 || endptr == ptr || h > UINT_MAX || h == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid height value in size message");
  }
 
  // Should end with newline or null terminator
  if (*endptr != '\n' && *endptr != '\0') {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid format: size message should end with newline or null terminator");
  }
 
  // Additional bounds checking
  if (w > 65535 || h > 65535) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Size values too large (max 65535)");
  }
 
  *width = (unsigned int)w;
  *height = (unsigned int)h;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, errno, ERROR_INVALID_PARAM, and SET_ERRNO.

◆ string_needs_shell_quoting()

bool string_needs_shell_quoting ( const char * str )

#include <string.h>

Check if a string needs shell quoting (contains spaces or special chars)

Parameters

str	String to check (must not be NULL)

Returns: true if string contains characters that require shell quoting, false otherwise

Detects if a string contains whitespace or special characters that require shell quoting when used in command-line arguments. Useful for determining whether to apply shell escaping functions.

CHARACTERS REQUIRING QUOTING:

Whitespace: space, tab
Special shell characters: " ' $ ` \ < > & ; | ( ) [ ] { } * ? ! ~ # @ - Control characters: newline, carriage return, etc. @note Empty strings return false (no quoting needed). @note Alphanumeric and some safe punctuation (- . _) return false. @par Example @code if (string_needs_shell_quoting("/path/to file.txt")) { // Path contains a space, needs quoting }

Definition at line 219 of file util/string.c.

                                                 {
  if (!str || str[0] == '\0') {
    return false; // Empty strings don't need quoting
  }
 
  // Check for characters that need shell quoting
  for (size_t i = 0; str[i] != '\0'; i++) {
    char c = str[i];
 
    // Whitespace characters always need quoting
    if (c == ' ' || c == '\t' || c == '\n' || c == '\r') {
      return true;
    }
 
    // Shell special characters
    if (c == '"' || c == '\'' || c == '$' || c == '`' || c == '\\' || c == '<' || c == '>' || c == '&' || c == ';' ||
        c == '|' || c == '(' || c == ')' || c == '[' || c == ']' || c == '{' || c == '}' || c == '*' || c == '?' ||
        c == '!' || c == '~' || c == '#' || c == '@') {
      return true;
    }
  }
 
  return false;
}

Referenced by escape_path_for_shell().

◆ strip_ansi_codes()

void strip_ansi_codes	(	const char *	input,
		char *	output,
		size_t	output_size
	)

#include <string.h>

Strip ANSI escape codes from a string.

Removes all ANSI escape sequences from the input string, suitable for displaying colored/styled text in environments that don't support ANSI codes (e.g., browser console, plain text output).

Handles patterns like:

\033[...m (color and style codes)
\033[0m (reset code)
\033[38;5;Nm (256-color codes)
\033[38;2;R;G;Bm (truecolor codes)
\033[2J, \033[H, etc. (cursor and screen control)

Parameters

input	Input string with ANSI codes (must not be NULL)
output	Output buffer for cleaned string (must not be NULL)
output_size	Size of output buffer (must be > 0)

EXAMPLE:

char input[] = "\\033[31mError\\033[0m";  // Red "Error" text
char output[256];
strip_ansi_codes(input, output, sizeof(output));
// output now contains "Error" without ANSI codes

Note: Output buffer must be large enough for input (worst case: same size).; Function truncates output if buffer is too small.; Safe for use with formatted log messages.

Definition at line 407 of file util/string.c.

                                                                           {
  if (!input || !output || output_size == 0) {
    return;
  }
 
  size_t out_idx = 0;
  size_t in_idx = 0;
 
  while (input[in_idx] != '\0' && out_idx < output_size - 1) {
    // Check for ANSI escape sequence: ESC[
    // Standard ANSI codes use escape character (0x1B or \033) followed by [
    if (input[in_idx] == '\033' && input[in_idx + 1] == '[') {
      in_idx += 2; // Skip \033[
 
      // Skip until we find the terminating letter (m is most common, also H, J, K, etc.)
      // This handles patterns like: 38;5;74m, 0m, 38;2;255;0;0m, 2J, H, etc.
      while (input[in_idx] != '\0') {
        if ((input[in_idx] >= 'A' && input[in_idx] <= 'Z') || (input[in_idx] >= 'a' && input[in_idx] <= 'z')) {
          in_idx++; // Skip the terminating letter
          break;
        }
        in_idx++;
      }
    } else {
      // Regular character (including [ in normal text), copy to output
      output[out_idx++] = input[in_idx++];
    }
  }
 
  output[out_idx] = '\0';
}

Referenced by platform_log_hook().

◆ truncate_with_ellipsis()

void truncate_with_ellipsis	(	const char *	input,
		char *	output,
		size_t	output_size,
		int	max_width
	)

#include <string.h>

Truncate a string to a maximum display width, with ellipsis.

Handles ANSI escape sequences (never cuts inside one), multi-byte UTF-8, and wide characters (CJK = 2 columns). If truncation is needed, appends a color reset (\033[0m) followed by "…" (Unicode ellipsis, 1 column).

Safe for strings with or without ANSI codes. For plain text the reset is harmless (terminals ignore redundant resets).

Parameters

input	Input string (may contain ANSI escape sequences and UTF-8)
output	Output buffer for truncated string
output_size	Size of output buffer (must be >= 10 for reset + ellipsis + NUL)
max_width	Maximum display width in columns

Definition at line 322 of file util/string.c.

                                                                                                {
  if (!input || !output || output_size < 4) {
    if (output && output_size > 0) {
      output[0] = '\0';
    }
    return;
  }
 
  int content_width = display_width(input);
 
  // Content fits — copy as-is
  if (content_width <= max_width) {
    size_t len = strlen(input);
    if (len >= output_size) {
      len = output_size - 1;
    }
    memcpy(output, input, len);
    output[len] = '\0';
    return;
  }
 
  // Need to truncate. Walk forward copying bytes while counting visible
  // columns. ANSI escape sequences are copied whole (zero display width).
  // UTF-8 multi-byte characters are decoded to get their display width
  // (e.g., CJK = 2 columns, emoji = 2 columns) and copied as whole
  // codepoints so we never split a multi-byte sequence.
  const char *src = input;
  const char *src_end = input + strlen(input);
  char *dst = output;
  char *dst_end = output + output_size - 10; // Reserve for reset + ellipsis + NUL
  int cols = 0;
  int target = max_width - 1; // Reserve 1 column for "…"
 
  if (target < 0) {
    target = 0;
  }
 
  while (src < src_end && dst < dst_end) {
    if (*src == '\x1b') {
      // Copy the entire escape sequence (zero display width)
      const char *esc_end = ansi_skip_escape(src, src_end);
      size_t esc_len = (size_t)(esc_end - src);
      if (dst + esc_len < dst_end) {
        memcpy(dst, src, esc_len);
        dst += esc_len;
      }
      src = esc_end;
    } else {
      // Decode one UTF-8 codepoint to get its byte length and display width
      utf8proc_int32_t codepoint;
      utf8proc_ssize_t cp_len = utf8proc_iterate((const utf8proc_uint8_t *)src, src_end - src, &codepoint);
      if (cp_len <= 0) {
        // Invalid UTF-8 — copy single byte, count as 1 column
        cp_len = 1;
        codepoint = (unsigned char)*src;
      }
 
      int char_width = utf8proc_charwidth(codepoint);
      if (char_width < 0) {
        char_width = 0; // Control characters
      }
 
      if (cols + char_width > target) {
        break;
      }
 
      // Copy the full codepoint bytes
      if (dst + cp_len < dst_end) {
        memcpy(dst, src, (size_t)cp_len);
        dst += cp_len;
      }
      src += cp_len;
      cols += char_width;
    }
  }
 
  // Reset colors and append ellipsis (U+2026, 3 bytes)
  size_t remaining = output_size - (size_t)(dst - output);
  int n = snprintf(dst, remaining, "\033[0m…");
  if (n > 0) {
    dst += n;
  }
  *dst = '\0';
}

References ansi_skip_escape(), and display_width().

◆ url_is_tcp()

bool url_is_tcp ( const char * url )

#include <url.h>

Check if a URL string is a valid TCP URL.

Parameters

url	URL string to validate

Returns: True if URL is valid and has TCP scheme, false otherwise

Parses a URL and checks if it has a TCP scheme. This is the primary function for TCP URL validation - use this instead of manually calling url_parse() and url_is_tcp_scheme().

Example: if (url_is_tcp("tcp://example.com:5000")) {

// Safe to use as TCP URL

connection_attempt_tcp(&ctx, "tcp://example.com:5000");

} else if (url_is_valid(address)) {

// Use regular HTTP(S) transport

}

connection_attempt_tcp
asciichat_error_t connection_attempt_tcp(connection_attempt_context_t *ctx, const char *server_address, uint16_t server_port)
Attempt direct TCP connection.
Definition connection_attempt.c:168

url_is_valid
bool url_is_valid(const char *url)
Fast URL validation using production-grade regex (HTTP/HTTPS/WebSocket/TCP)
Definition url.c:81

url_is_tcp
bool url_is_tcp(const char *url)
Check if a URL string is a valid TCP URL.
Definition url.c:342

Definition at line 342 of file url.c.

                                 {
  if (!url || !*url) {
    SET_ERRNO(ERROR_INVALID_PARAM, "url is NULL or empty");
    return false;
  }
 
  /* Parse URL to validate and check scheme */
  url_parts_t parts = {0};
  asciichat_error_t result = url_parse(url, &parts);
  bool is_tcp = (result == ASCIICHAT_OK && url_is_tcp_scheme(parts.scheme));
  url_parts_destroy(&parts);
 
  return is_tcp;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, url_parts_t::scheme, SET_ERRNO, url_is_tcp_scheme(), url_parse(), and url_parts_destroy().

Referenced by connection_endpoint_resolve().

◆ url_is_tcp_scheme()

bool url_is_tcp_scheme ( const char * scheme )

#include <url.h>

Check if URL scheme is TCP.

Parameters

scheme Scheme string to check (case-insensitive)

Returns: True if scheme is "tcp", false otherwise

Utility function to determine if a parsed URL is a TCP URL.

Example: url_parts_t parts = {0};

if (url_parse("tcp://example.com:5000", &parts) == ASCIICHAT_OK) {

if (url_is_tcp_scheme(parts.scheme)) {

// Handle TCP connection

}

url_parts_destroy(&parts);

}

Definition at line 332 of file url.c.

                                           {
  if (!scheme || !*scheme) {
    SET_ERRNO(ERROR_INVALID_PARAM, "scheme is NULL or empty");
    return false;
  }
 
  /* Case-insensitive comparison for "tcp" */
  return (strcasecmp(scheme, "tcp") == 0);
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by url_is_tcp().

◆ url_is_valid()

bool url_is_valid ( const char * url )

#include <url.h>

Fast URL validation using production-grade regex (HTTP/HTTPS/WebSocket/TCP)

Parameters

url	Input URL string to validate

Returns: True if URL is valid, false otherwise

Quickly validates a URL without extracting components. Uses PCRE2 with JIT compilation for 10-100x performance over manual parsing.

URL ACCEPTANCE CRITERIA:

Scheme: http, https, ws, wss, or tcp (case-insensitive)
Host: Public IPv4, IPv6, localhost, FQDN, or bare hostname
Rejects: Private IPs (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x)
Port: Optional, must be 1-65535 if present
Path: Optional, may include query and fragment

Example: if (url_is_valid("https://github.com/octocat")) {

// Safe to use URL

}

Definition at line 81 of file url.c.

                                   {
  if (!url || !*url) {
    SET_ERRNO(ERROR_INVALID_PARAM, "URL is NULL or empty");
    return false;
  }
 
  pcre2_code *regex = url_regex_get();
  if (!regex) {
    return false;
  }
 
  /* Check if URL needs http:// prefix (bare hostname or IP) */
  char url_with_scheme[2048];
  const char *url_to_match = url;
 
  if (!strstr(url, "://")) {
    /* No scheme - check if it looks like a bare hostname/IP */
 
    /* Reject bare scheme words like "http", "https", "ftp" */
    if (strcmp(url, "http") == 0 || strcmp(url, "https") == 0 || strcmp(url, "ftp") == 0 || strcmp(url, "ftps") == 0) {
      return false;
    }
 
    /* Reject URLs that look like malformed schemes (http/ instead of http://) */
    if (strncmp(url, "http/", 5) == 0 || strncmp(url, "https/", 6) == 0) {
      return false;
    }
 
    /* Reject if it contains @ (email-like) */
    if (strchr(url, '@')) {
      return false;
    }
 
    /* Reject pure hex strings (raw keys, not hostnames) */
    if (strlen(url) == 64) {
      bool all_hex = true;
      for (const char *p = url; *p && all_hex; p++) {
        if (!((*p >= '0' && *p <= '9') || (*p >= 'a' && *p <= 'f') || (*p >= 'A' && *p <= 'F'))) {
          all_hex = false;
        }
      }
      if (all_hex) {
        return false; /* Looks like raw hex key, not hostname */
      }
    }
 
    /* Check colon handling */
    const char *colon_pos = strchr(url, ':');
    if (colon_pos) {
      /* Has colon - reject unless colon is followed by port number */
      const char *after_colon = colon_pos + 1;
      bool looks_like_port = true;
      for (const char *p = after_colon; *p && *p != '/'; p++) {
        if (!(*p >= '0' && *p <= '9')) {
          looks_like_port = false;
          break;
        }
      }
      if (!looks_like_port) {
        return false; /* Colon but not a port number */
      }
    }
 
    /* Looks like a bare hostname/IP - prepend http:// */
    int result = snprintf(url_with_scheme, sizeof(url_with_scheme), "http://%s", url);
    if (result < 0 || result >= (int)sizeof(url_with_scheme)) {
      return false; /* URL too long */
    }
    url_to_match = url_with_scheme;
  }
 
  pcre2_match_data *match_data = pcre2_match_data_create_from_pattern(regex, NULL);
  if (!match_data) {
    return false;
  }
 
  /* Perform JIT match (falls back to interpreted if JIT unavailable) */
  int rc = asciichat_pcre2_match(regex, (PCRE2_SPTR)url_to_match, strlen(url_to_match), 0, /* startoffset */
                                 0,                                                        /* options */
                                 match_data, NULL);                                        /* mcontext */
 
  pcre2_match_data_free(match_data);
  return rc >= 0; /* rc >= 0 means successful match */
}

References asciichat_pcre2_match(), ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by ffmpeg_decoder_create(), options_init(), parse_public_key(), and yt_dlp_extract_stream_url().

◆ url_is_websocket()

bool url_is_websocket ( const char * url )

#include <url.h>

Check if a URL string is a valid WebSocket URL.

Parameters

url	URL string to validate

Returns: True if URL is valid and has WebSocket scheme (ws or wss), false otherwise

Parses a URL and checks if it has a WebSocket scheme. This is the primary function for WebSocket URL validation - use this instead of manually calling url_parse() and url_is_websocket_scheme().

Example: if (url_is_websocket("wss://example.com:443")) {

// Safe to use as WebSocket URL

connection_attempt_websocket(&ctx, "wss://example.com:443");

} else if (url_is_valid(address)) {

// Use regular HTTP(S) transport

}

connection_attempt_websocket
asciichat_error_t connection_attempt_websocket(connection_attempt_context_t *ctx, const char *ws_url)
Attempt WebSocket connection (ws:// or wss://)
Definition connection_attempt.c:436

url_is_websocket
bool url_is_websocket(const char *url)
Check if a URL string is a valid WebSocket URL.
Definition url.c:307

Definition at line 307 of file url.c.

                                       {
  if (!url || !*url) {
    SET_ERRNO(ERROR_INVALID_PARAM, "url is NULL or empty");
    return false;
  }
 
  /* Parse URL to validate and check scheme */
  url_parts_t parts = {0};
  asciichat_error_t result = url_parse(url, &parts);
  bool is_ws = (result == ASCIICHAT_OK && url_is_websocket_scheme(parts.scheme));
  url_parts_destroy(&parts);
 
  return is_ws;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, url_parts_t::scheme, SET_ERRNO, url_is_websocket_scheme(), url_parse(), and url_parts_destroy().

Referenced by client_main(), and connection_endpoint_resolve().

◆ url_is_websocket_scheme()

bool url_is_websocket_scheme ( const char * scheme )

#include <url.h>

Check if URL scheme is WebSocket (ws or wss)

Parameters

scheme Scheme string to check (case-insensitive)

Returns: True if scheme is "ws" or "wss", false otherwise

Utility function to determine if a parsed URL is a WebSocket URL.

Example: url_parts_t parts = {0};

if (url_parse("wss://example.com:443", &parts) == ASCIICHAT_OK) {

if (url_is_websocket_scheme(parts.scheme)) {

// Handle WebSocket connection

}

url_parts_destroy(&parts);

}

Definition at line 297 of file url.c.

                                                 {
  if (!scheme || !*scheme) {
    SET_ERRNO(ERROR_INVALID_PARAM, "scheme is NULL or empty");
    return false;
  }
 
  /* Case-insensitive comparison for "ws" or "wss" */
  return (strcasecmp(scheme, "ws") == 0 || strcasecmp(scheme, "wss") == 0);
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by url_is_websocket().

◆ url_looks_like_tcp()

bool url_looks_like_tcp ( const char * url )

#include <url.h>

Quick check if a string is a TCP URL.

Parameters

url	String to check

Returns: True if string starts with tcp://, false otherwise

Fast check without full URL parsing. Useful for determining transport type.

Example: if (url_looks_like_tcp("tcp://example.com:5000")) {

// Use TCP transport

} else if (url_is_valid(address)) {

// Use regular HTTP(S) transport

}

url_looks_like_tcp
bool url_looks_like_tcp(const char *url)
Quick check if a string is a TCP URL.
Definition url.c:357

Definition at line 357 of file url.c.

                                         {
  if (!url || !*url) {
    SET_ERRNO(ERROR_INVALID_PARAM, "url is NULL or empty");
    return false;
  }
 
  /* Quick check for tcp:// prefix (case-insensitive) */
  return (strncasecmp(url, "tcp://", 6) == 0);
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

◆ url_looks_like_websocket()

bool url_looks_like_websocket ( const char * url )

#include <url.h>

Quick check if a string is a WebSocket URL.

Parameters

url	String to check

Returns: True if string starts with ws:// or wss://, false otherwise

Fast check without full URL parsing. Useful for determining transport type.

Example: if (url_looks_like_websocket("wss://example.com:443")) {

// Use WebSocket transport

} else if (url_is_valid(address)) {

// Use regular HTTP(S) transport

}

url_looks_like_websocket
bool url_looks_like_websocket(const char *url)
Quick check if a string is a WebSocket URL.
Definition url.c:322

Definition at line 322 of file url.c.

                                               {
  if (!url || !*url) {
    SET_ERRNO(ERROR_INVALID_PARAM, "url is NULL or empty");
    return false;
  }
 
  /* Quick check for ws:// or wss:// prefix (case-insensitive) */
  return (strncasecmp(url, "ws://", 5) == 0 || strncasecmp(url, "wss://", 6) == 0);
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

◆ url_parse()

asciichat_error_t url_parse	(	const char *	url,
		url_parts_t *	parts_out
	)

#include <url.h>

Parse HTTP(S), WebSocket, and TCP URL into components.

Parameters

url	Input URL string to parse
parts_out	Output structure for parsed components (must not be NULL)

Returns: ASCIICHAT_OK on success, error code on failure

Validates and parses an HTTP(S), WebSocket, or TCP URL into its component parts using production-grade PCRE2 regex with JIT compilation.

URL ACCEPTANCE CRITERIA:

Scheme: http, https, ws, wss, or tcp (case-insensitive)
Host: Public IPv4, IPv6, localhost, FQDN, or bare hostname
Rejects: Private IPs (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x)
Port: Optional, 1-65535
Path/Query/Fragment: Optional

EXTRACTED COMPONENTS:

scheme: "http", "https", "ws", "wss", or "tcp" (always present)
host: Hostname, IPv4, or IPv6 (always present)
port: Port number (0 if not specified)
userinfo: user:pass@ prefix (NULL if not present)
ipv6: IPv6 address (NULL unless host is bracketed IPv6)
path: Path, query, and fragment (NULL if not present)

MEMORY MANAGEMENT:

All allocated strings must be freed using url_parts_destroy(parts_out)
Do NOT use SAFE_FREE() on individual fields - use url_parts_destroy()

Note: Returns ERROR_INVALID_PARAM if URL format is invalid; Returns ERROR_MEMORY if allocation fails

Example: url_parts_t parts = {0};

if (url_parse("https://user:pass@example.com:8443/api/v1?key=val#section", &parts) == ASCIICHAT_OK) {

printf("Host: %s, Port: %d, Path: %s\\n", parts.host, parts.port, parts.path);

url_parts_destroy(&parts);

}

url_parts_t::path
char * path
Extracted path, query, and fragment (allocated if present, may be NULL)
Definition url.h:63

url_parts_t::host
char * host
Extracted hostname or IP address (allocated)
Definition url.h:60

url_parts_t::port
int port
Extracted port number (0 if not specified)
Definition url.h:62

Definition at line 166 of file url.c.

                                                                     {
  if (!url || !*url) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "URL is NULL or empty");
  }
 
  if (!parts_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "parts_out is NULL");
  }
 
  /* Clear output structure */
  memset(parts_out, 0, sizeof(*parts_out));
 
  pcre2_code *regex = url_regex_get();
  if (!regex) {
    return SET_ERRNO(ERROR_CONFIG, "URL validator not initialized");
  }
 
  /* Check if URL needs http:// prefix (bare hostname or IP) */
  // allocate twice the "safe limit" of 2048 for website URLs, even though modern browsers can handle up
  // to 80k character URLs in some cases.
  char url_with_scheme[4096];
  const char *url_to_match = url;
  const char *original_url = url;
 
  if (!strstr(url, "://")) {
    /* No scheme - check if it looks like a bare hostname/IP */
 
    /* Reject bare scheme words like "http", "https", "ftp" */
    if (strcmp(url, "http") == 0 || strcmp(url, "https") == 0 || strcmp(url, "ftp") == 0 || strcmp(url, "ftps") == 0) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid URL format: %s", url);
    }
 
    /* Reject URLs that look like malformed schemes (http/ instead of http://) */
    if (strncmp(url, "http/", 5) == 0 || strncmp(url, "https/", 6) == 0) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid URL format (looks like malformed scheme): %s", url);
    }
 
    /* Reject pure hex strings (raw keys, not hostnames) */
    if (strlen(url) == 64) {
      bool all_hex = true;
      for (const char *p = url; *p && all_hex; p++) {
        if (!((*p >= '0' && *p <= '9') || (*p >= 'a' && *p <= 'f') || (*p >= 'A' && *p <= 'F'))) {
          all_hex = false;
        }
      }
      if (all_hex) {
        return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid URL: appears to be raw hex data, not a URL");
      }
    }
 
    const char *colon_pos = strchr(url, ':');
    if (colon_pos) {
      /* Has colon - check if what follows is numeric (port) */
      const char *after_colon = colon_pos + 1;
      bool looks_like_port = true;
      for (const char *p = after_colon; *p && *p != '/'; p++) {
        if (!(*p >= '0' && *p <= '9')) {
          looks_like_port = false;
          break;
        }
      }
      if (!looks_like_port) {
        return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid URL format (invalid scheme): %s", url);
      }
    }
 
    /* Looks like a bare hostname/IP - prepend http:// */
    int result = snprintf(url_with_scheme, sizeof(url_with_scheme), "http://%s", url);
    if (result < 0 || result >= (int)sizeof(url_with_scheme)) {
      return SET_ERRNO(ERROR_INVALID_PARAM, "URL too long");
    }
    url_to_match = url_with_scheme;
  }
 
  pcre2_match_data *match_data = pcre2_match_data_create_from_pattern(regex, NULL);
  if (!match_data) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to create match data");
  }
 
  /* Perform JIT match (falls back to interpreted if JIT unavailable) */
  int rc = asciichat_pcre2_match(regex, (PCRE2_SPTR)url_to_match, strlen(url_to_match), 0, /* startoffset */
                                 0,                                                        /* options */
                                 match_data, NULL);                                        /* mcontext */
 
  if (rc < 0) {
    pcre2_match_data_free(match_data);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid URL format: %s", original_url);
  }
 
  /* Extract named groups */
  parts_out->scheme = asciichat_pcre2_extract_named_group(regex, match_data, "scheme", url_to_match);
  parts_out->userinfo = asciichat_pcre2_extract_named_group(regex, match_data, "userinfo", url_to_match);
  parts_out->host = asciichat_pcre2_extract_named_group(regex, match_data, "host", url_to_match);
  parts_out->ipv6 = asciichat_pcre2_extract_named_group(regex, match_data, "ipv6", url_to_match);
  parts_out->path = asciichat_pcre2_extract_named_group(regex, match_data, "path_query_fragment", url_to_match);
 
  /* Extract port number */
  parts_out->port = 0;
  char *port_str = asciichat_pcre2_extract_named_group(regex, match_data, "port", url_to_match);
  if (port_str) {
    parts_out->port = (int)strtol(port_str, NULL, 10);
    SAFE_FREE(port_str);
  }
 
  pcre2_match_data_free(match_data);
 
  /* Verify we got required fields */
  if (!parts_out->scheme || !parts_out->host) {
    url_parts_destroy(parts_out);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing required URL components");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, asciichat_pcre2_extract_named_group(), asciichat_pcre2_match(), ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_MEMORY, url_parts_t::host, url_parts_t::ipv6, url_parts_t::path, url_parts_t::port, SAFE_FREE, url_parts_t::scheme, SET_ERRNO, url_parts_destroy(), and url_parts_t::userinfo.

Referenced by connection_endpoint_resolve(), parse_public_key(), url_is_tcp(), and url_is_websocket().

◆ url_parts_destroy()

void url_parts_destroy ( url_parts_t * parts )

#include <url.h>

Free parsed URL components.

Parameters

parts Pointer to url_parts_t structure to free

Safely frees all allocated string fields in a url_parts_t structure. Safe to call multiple times on same structure.

Example: url_parts_t parts = {0};

url_parse("https://example.com", &parts);

// Use parts...

url_parts_destroy(&parts);

// All internal strings are freed, parts is zeroed

Definition at line 281 of file url.c.

                                           {
  if (!parts) {
    SET_ERRNO(ERROR_INVALID_PARAM, "parts is NULL");
    return;
  }
 
  SAFE_FREE(parts->scheme);
  SAFE_FREE(parts->userinfo);
  SAFE_FREE(parts->host);
  SAFE_FREE(parts->ipv6);
  SAFE_FREE(parts->path);
  parts->port = 0;
 
  memset(parts, 0, sizeof(*parts));
}

References ERROR_INVALID_PARAM, url_parts_t::host, url_parts_t::ipv6, url_parts_t::path, url_parts_t::port, SAFE_FREE, url_parts_t::scheme, SET_ERRNO, and url_parts_t::userinfo.

Referenced by connection_endpoint_resolve(), parse_public_key(), url_is_tcp(), url_is_websocket(), and url_parse().

◆ utf8_char_count()

size_t utf8_char_count ( const char * str )

#include <utf8.h>

Count UTF-8 characters (not bytes)

Parameters

str	String to count (must not be NULL)

Returns: Number of UTF-8 characters, or SIZE_MAX if invalid UTF-8 detected

Counts the number of Unicode codepoints in the string, not byte count. Properly handles multi-byte UTF-8 sequences (1-4 bytes per character).

Returns SIZE_MAX if the string contains invalid UTF-8 sequences.

Note: Empty string has 0 characters; Returns SIZE_MAX for NULL input or invalid UTF-8; Slower than strlen() but necessary for correct UTF-8 processing; Used by Levenshtein distance and other algorithms needing character counts

Example: // Check if password is long enough (in characters, not bytes)

size_t pwd_len = utf8_char_count(password);

if (pwd_len == SIZE_MAX) {

log_error("Password contains invalid UTF-8");

return false;

}

if (pwd_len < 8) {

return false; // Too short

}

utf8_char_count
size_t utf8_char_count(const char *str)
Count UTF-8 characters (not bytes)
Definition utf8.c:136

Definition at line 136 of file utf8.c.

                                        {
  if (!str) {
    SET_ERRNO(ERROR_INVALID_PARAM, "str is NULL");
    return -1; // SIZE_MAX
  }
 
  size_t count = 0;
  const uint8_t *p = (const uint8_t *)str;
  while (*p) {
    uint32_t codepoint;
    int decode_len = utf8_decode(p, &codepoint);
    if (decode_len < 0) {
      return -1; // SIZE_MAX - Invalid UTF-8
    }
    count++;
    p += decode_len;
  }
  return count;
}

References ERROR_INVALID_PARAM, SET_ERRNO, and utf8_decode().

Referenced by levenshtein(), and utf8_is_valid().

◆ utf8_continuation_bytes_needed()

int utf8_continuation_bytes_needed ( unsigned char first_byte )

#include <utf8.h>

Determine how many additional bytes are needed to complete a UTF-8 character.

Parameters

first_byte The first byte of a potential UTF-8 sequence

Returns: Number of continuation bytes needed (0-3), or -1 if invalid start byte

Given the first byte of a UTF-8 sequence, determines how many additional bytes are needed to complete the character. Returns 0 for ASCII (1-byte chars), 1 for 2-byte sequences, 2 for 3-byte sequences, 3 for 4-byte sequences.

Useful in interactive input loops where bytes arrive one at a time and you need to know when a complete UTF-8 character has been received.

Example: // Read multi-byte UTF-8 character interactively

unsigned char first_byte = getchar();

int continuation_bytes = utf8_continuation_bytes_needed(first_byte);

if (continuation_bytes < 0) {

// Invalid start byte

continue;

}

// Read continuation_bytes more bytes

for (int i = 0; i < continuation_bytes; i++) {

unsigned char next_byte = getchar();

// Validate it's a continuation byte (10xxxxxx)

if ((next_byte & 0xC0) != 0x80) {

// Invalid continuation byte

break;

}

}

utf8_continuation_bytes_needed
int utf8_continuation_bytes_needed(unsigned char first_byte)
Determine how many additional bytes are needed to complete a UTF-8 character.
Definition utf8.c:222

Definition at line 222 of file utf8.c.

                                                             {
  if ((first_byte & 0x80) == 0) {
    return 0; // ASCII (0xxxxxxx) - single byte, no continuation needed
  }
  if ((first_byte & 0xE0) == 0xC0) {
    return 1; // 110xxxxx - 2 byte sequence, 1 continuation byte needed
  }
  if ((first_byte & 0xF0) == 0xE0) {
    return 2; // 1110xxxx - 3 byte sequence, 2 continuation bytes needed
  }
  if ((first_byte & 0xF8) == 0xF0) {
    return 3; // 11110xxx - 4 byte sequence, 3 continuation bytes needed
  }
  return -1; // Invalid UTF-8 start byte
}

◆ utf8_decode()

int utf8_decode	(	const uint8_t *	s,
		uint32_t *	codepoint
	)

#include <utf8.h>

Decode a UTF-8 sequence to a Unicode codepoint.

Parameters

s	Pointer to UTF-8 byte sequence (must not be NULL)
codepoint	Output parameter for decoded codepoint (must not be NULL)

Returns: Number of bytes consumed (1-4), or -1 if invalid sequence

Decodes a UTF-8 byte sequence starting at s to a Unicode codepoint. Validates the UTF-8 encoding during decoding and returns the number of bytes consumed. Returns -1 if the sequence is invalid (overlong encoding, invalid bytes, etc.).

Note: Input pointer must point to the start of a valid UTF-8 sequence.; Output codepoint is set even if sequence is invalid (check return value).; Function does not advance the pointer - caller must advance by return value.; Return value of -1 indicates invalid UTF-8 sequence.

Example: const uint8_t *str = (uint8_t*)"Hello 世界";

uint32_t cp;

int len;

// Decode 'H' (1 byte)

len = utf8_decode(str, &cp); // Returns 1, cp = 'H'

str += len;

// Decode '世' (3 bytes)

len = utf8_decode(str, &cp); // Returns 3, cp = U+4E16

str += len;

Definition at line 18 of file utf8.c.

                                                       {
  if (s[0] < 0x80) {
    *codepoint = s[0];
    return 1;
  }
  if ((s[0] & 0xE0) == 0xC0) {
    // Validate continuation byte
    if ((s[1] & 0xC0) != 0x80)
      return -1;
    *codepoint = (((uint32_t)(s[0] & 0x1F) << 6) | (uint32_t)(s[1] & 0x3F));
    return 2;
  } else if ((s[0] & 0xF0) == 0xE0) {
    // Validate continuation bytes
    if ((s[1] & 0xC0) != 0x80 || (s[2] & 0xC0) != 0x80)
      return -1;
    *codepoint = (((uint32_t)(s[0] & 0x0F) << 12) | ((uint32_t)(s[1] & 0x3F) << 6) | (uint32_t)(s[2] & 0x3F));
    return 3;
  } else if ((s[0] & 0xF8) == 0xF0) {
    // Validate continuation bytes
    if ((s[1] & 0xC0) != 0x80 || (s[2] & 0xC0) != 0x80 || (s[3] & 0xC0) != 0x80)
      return -1;
    *codepoint = (((uint32_t)(s[0] & 0x07) << 18) | ((uint32_t)(s[1] & 0x3F) << 12) | ((uint32_t)(s[2] & 0x3F) << 6) |
                  (uint32_t)(s[3] & 0x3F));
    return 4;
  }
  return -1; // Invalid
}

Referenced by digital_rain_apply(), log_search_get_match_info(), utf8_char_count(), utf8_to_codepoints(), and validate_shell_safe().

◆ utf8_display_width()

int utf8_display_width ( const char * str )

#include <utf8.h>

Calculate terminal display width of a UTF-8 string.

Parameters

str	UTF-8 string (must not be NULL)

Returns: Display width in terminal columns (0 on empty or invalid input)

Converts UTF-8 byte sequences to Unicode codepoints and calculates the terminal display width using utf8proc_charwidth(). Properly handles:

Multi-byte UTF-8 sequences (1-4 bytes per character)
Wide characters (CJK, emoji - typically 2 columns)
Control characters and combining marks (0 width)
Invalid UTF-8 sequences (stops processing)

Terminal display width differs from byte count:

ASCII 'A' = 1 byte = 1 column
'é' (é) = 2 bytes = 1 column
'中' (CJK) = 3 bytes = 2 columns
'😀' (emoji) = 4 bytes = 2 columns

Note: Uses utf8proc library for accurate Unicode character-width computation; Returns 0 for NULL or empty string; Invalid UTF-8 sequences stop processing (partial width returned)

Example: int width = utf8_display_width("Hello"); // Returns 5 (5 ASCII chars)

int width = utf8_display_width("Café"); // Returns 4 (é is 1 column)

int width = utf8_display_width("中国"); // Returns 4 (2 CJK chars × 2 columns)

int width = utf8_display_width("😀"); // Returns 2 (emoji is 2 columns)

Definition at line 46 of file utf8.c.

                                        {
  if (!str || !*str) {
    return 0;
  }
 
  int width = 0;
  const utf8proc_uint8_t *p = (const utf8proc_uint8_t *)str;
 
  while (*p) {
    // Skip ANSI escape sequences (ESC [ ... m)
    // Pattern: \x1b [ [0-9;]* m
    if (p[0] == 0x1b && p[1] == '[') {
      // Found ANSI escape sequence start
      p += 2; // Skip ESC[
      // Skip digits and semicolons until we find 'm'
      while (*p && *p != 'm') {
        p++;
      }
      if (*p == 'm') {
        p++; // Skip the 'm'
      }
      continue;
    }
 
    utf8proc_int32_t codepoint;
    utf8proc_ssize_t len = utf8proc_iterate(p, -1, &codepoint);
 
    if (len <= 0) {
      // End of string or invalid UTF-8 sequence, stop processing
      break;
    }
 
    // Get display width of this codepoint
    int char_width = utf8proc_charwidth(codepoint);
    if (char_width < 0) {
      // Control character or unprintable - treat as 0 width
      char_width = 0;
    }
    width += char_width;
    p += len;
  }
 
  return width;
}

Referenced by display_height(), display_width(), layout_print_two_column_row(), options_config_calculate_max_col_width(), prompt_password(), and validate_palette_chars().

◆ utf8_display_width_n()

int utf8_display_width_n	(	const char *	str,
		size_t	max_bytes
	)

#include <utf8.h>

Calculate terminal display width of a UTF-8 string up to byte limit.

Parameters

str	UTF-8 string (must not be NULL)
max_bytes	Maximum bytes to process

Returns: Display width in terminal columns

Like utf8_display_width() but stops after processing max_bytes bytes. Useful for calculating display width of substrings or with length-limited buffers.

Note: Stops processing at max_bytes boundary or null terminator, whichever comes first; Invalid UTF-8 sequences stop processing (partial width returned); Uses utf8proc library for accurate Unicode character-width computation

Example: const char *str = "Hello World";

int width = utf8_display_width_n(str, 5); // Returns 5 (width of "Hello")

utf8_display_width_n
int utf8_display_width_n(const char *str, size_t max_bytes)
Calculate terminal display width of a UTF-8 string up to byte limit.
Definition utf8.c:91

Definition at line 91 of file utf8.c.

                                                            {
  if (!str || max_bytes == 0) {
    return 0;
  }
 
  int width = 0;
  const utf8proc_uint8_t *p = (const utf8proc_uint8_t *)str;
  const utf8proc_uint8_t *end = p + max_bytes;
 
  while (p < end && *p) {
    // Skip ANSI escape sequences (ESC [ ... m)
    if (p + 1 < end && p[0] == 0x1b && p[1] == '[') {
      // Found ANSI escape sequence start
      p += 2; // Skip ESC[
      // Skip digits and semicolons until we find 'm'
      while (p < end && *p && *p != 'm') {
        p++;
      }
      if (p < end && *p == 'm') {
        p++; // Skip the 'm'
      }
      continue;
    }
 
    utf8proc_int32_t codepoint;
    utf8proc_ssize_t len = utf8proc_iterate(p, end - p, &codepoint);
 
    if (len <= 0) {
      // End of string or invalid UTF-8 sequence
      break;
    }
 
    // Get display width of this codepoint
    int char_width = utf8proc_charwidth(codepoint);
    if (char_width < 0) {
      // Control character or unprintable - treat as 0 width
      char_width = 0;
    }
    width += char_width;
    p += len;
  }
 
  return width;
}

Referenced by utf8_palette_create().

◆ utf8_is_ascii_only()

bool utf8_is_ascii_only ( const char * str )

#include <utf8.h>

Check if a string contains only ASCII characters.

Parameters

str	String to check (must not be NULL)

Returns: true if all characters are ASCII (0x00-0x7F), false if any non-ASCII found

Validates UTF-8 encoding and checks that all decoded codepoints are ASCII. Useful for security-sensitive strings that should only contain ASCII (e.g., session identifiers to prevent homograph attacks).

Returns false if string contains invalid UTF-8 sequences.

Note: Empty string is considered ASCII-only (returns true); Returns false for NULL input (not validated); Prevents homograph attack vector (e.g., Cyrillic 'а' vs ASCII 'a')

Example: // Verify session string contains only ASCII to prevent homograph spoofing

if (!utf8_is_ascii_only(session_string)) {

log_warn("Session string contains non-ASCII characters");

return false;

}

utf8_is_ascii_only
bool utf8_is_ascii_only(const char *str)
Check if a string contains only ASCII characters.
Definition utf8.c:165

Definition at line 165 of file utf8.c.

                                         {
  if (!str) {
    SET_ERRNO(ERROR_INVALID_PARAM, "str is NULL");
    return false;
  }
 
  // Fast path: Check if all bytes are in ASCII range (0x00-0x7F)
  // ASCII characters are 0x00-0x7F (single byte, high bit clear)
  // Multi-byte UTF-8 has continuation bytes with high bit set (10xxxxxx pattern)
  // So if all bytes have high bit clear, it's guaranteed ASCII-only
  const unsigned char *p = (const unsigned char *)str;
  while (*p) {
    if ((*p & ~0x7F) != 0) {
      return false; // Non-ASCII byte found (high bit set)
    }
    p++;
  }
  return true;
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by is_session_string(), and options_init().

◆ utf8_is_valid()

bool utf8_is_valid ( const char * str )

#include <utf8.h>

Check if a string is valid UTF-8.

Parameters

str	String to validate (must not be NULL)

Returns: true if valid UTF-8, false if invalid sequences detected

Scans the entire string and validates that all byte sequences conform to UTF-8 encoding rules. Returns false immediately on first invalid sequence.

Note: Returns true for empty string (valid); Returns false for NULL input (not validated); More efficient than decoding all codepoints if only validation is needed

Example: if (!utf8_is_valid(user_input)) {

log_error("Invalid UTF-8 in user input");

return false;

}

Definition at line 156 of file utf8.c.

                                    {
  if (!str) {
    SET_ERRNO(ERROR_INVALID_PARAM, "str is NULL");
    return false;
  }
  // Reuse utf8_char_count to validate without duplicating loop
  return utf8_char_count(str) != (size_t)-1;
}

References ERROR_INVALID_PARAM, SET_ERRNO, and utf8_char_count().

Referenced by options_init(), prompt_password(), prompt_password_simple(), validate_private_key(), validate_public_key(), and validate_shell_safe().

◆ utf8_next_char_bytes()

int utf8_next_char_bytes	(	const char *	str,
		size_t	max_bytes
	)

#include <utf8.h>

Get byte length of next UTF-8 character.

Parameters

str	Pointer to UTF-8 byte sequence (must not be NULL)
max_bytes	Maximum bytes to read from str

Returns: Number of bytes in next character (1-4), or -1 if invalid UTF-8

Determines how many bytes are needed for the next complete UTF-8 character. Uses utf8proc for robust UTF-8 handling.

Useful for interactive text input where you need to handle multi-byte UTF-8 characters character-by-character (e.g., password prompts).

Note: Returns -1 for invalid UTF-8 sequences or if end of string reached; Requires utf8proc library which is already a project dependency

Example: // Handle multi-byte UTF-8 in password input

const char *input = "café";

int bytes_in_char = utf8_next_char_bytes(input, strlen(input));

// Returns 1 for 'c', 1 for 'a', 1 for 'f', 2 for 'é'

utf8_next_char_bytes
int utf8_next_char_bytes(const char *str, size_t max_bytes)
Get byte length of next UTF-8 character.
Definition utf8.c:205

Definition at line 205 of file utf8.c.

                                                            {
  if (!str || max_bytes == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "str is NULL or max_bytes is 0");
    return -1;
  }
 
  // Use utf8proc_iterate to get byte length of next character
  utf8proc_int32_t codepoint;
  utf8proc_ssize_t len = utf8proc_iterate((const utf8proc_uint8_t *)str, (utf8proc_ssize_t)max_bytes, &codepoint);
 
  if (len <= 0) {
    return -1; // Invalid UTF-8 or end of string
  }
 
  return (int)len;
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by layout_print_wrapped_description().

◆ utf8_read_and_insert_continuation_bytes()

int utf8_read_and_insert_continuation_bytes	(	char *	buffer,
		size_t *	cursor,
		size_t *	len,
		size_t	max_len,
		int	continuation_bytes,
		int(*)(void)	read_byte_fn
	)

#include <utf8.h>

Read continuation bytes and insert them into buffer at cursor position.

Parameters

buffer	Text buffer to insert bytes into
cursor	Current cursor position (modified to reflect new position)
len	Current buffer length (modified to reflect new length)
max_len	Maximum buffer size
continuation_bytes	Number of continuation bytes to read
read_byte_fn	Callback function to read next byte (should return int like getchar)

Returns: 0 on success, -1 if EOF or buffer overflow

Reads continuation_bytes bytes from input using the provided callback function, shifts existing buffer content right, and inserts each byte at the cursor position. Updates cursor and len to reflect the new state.

Useful for handling multi-byte UTF-8 input in interactive prompts where bytes arrive one at a time (password input, terminal prompts, etc).

Example: // In interactive password input

int continuation_bytes = utf8_continuation_bytes_needed((unsigned char)first_byte);

if (continuation_bytes > 0) {

int result = utf8_read_and_insert_continuation_bytes(

buffer, &cursor, &len, max_len, continuation_bytes, getchar);

if (result < 0) {

// Handle EOF or overflow

}

}

utf8_read_and_insert_continuation_bytes
int utf8_read_and_insert_continuation_bytes(char *buffer, size_t *cursor, size_t *len, size_t max_len, int continuation_bytes, int(*read_byte_fn)(void))
Read continuation bytes and insert them into buffer at cursor position.
Definition utf8.c:238

Definition at line 238 of file utf8.c.

                                                                                               {
  if (!buffer || !cursor || !len || continuation_bytes <= 0 || !read_byte_fn) {
    SET_ERRNO(ERROR_INVALID_PARAM, "invalid params");
    return -1;
  }
 
  for (int i = 0; i < continuation_bytes && *len < max_len - 1; i++) {
    int next_byte = read_byte_fn();
    if (next_byte == EOF) {
      return -1; // EOF reached
    }
 
    // Shift characters right to make room
    memmove(&buffer[*cursor + 1], &buffer[*cursor], *len - *cursor);
    buffer[*cursor] = (char)next_byte;
    (*len)++;
    (*cursor)++;
  }
 
  return 0;
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

◆ utf8_strcasestr()

const char * utf8_strcasestr	(	const char *	haystack,
		const char *	needle
	)

#include <utf8.h>

Case-insensitive substring search with full Unicode support.

Parameters

haystack	String to search in (must not be NULL)
needle	Substring to search for (must not be NULL)

Returns: Pointer to first occurrence of needle in haystack, or NULL if not found

Performs case-insensitive substring search using Unicode case folding. Properly handles all Unicode characters including accented letters, Greek, Cyrillic, CJK, emoji, and other scripts.

Uses utf8proc library for accurate Unicode case folding according to Unicode standard. This ensures correct matching for:

ASCII: "TEST" matches "test"
Accented: "CAFÉ" matches "café"
Greek: "ΕΛΛΗΝΙΚΆ" matches "ελληνικά"
Cyrillic: "РУССКИЙ" matches "русский"

Note: Returns NULL if needle is empty string; Returns haystack if needle is empty; Case folding follows Unicode standard (more complex than simple toupper/tolower); Uses utf8proc for accurate Unicode handling

Example: const char *found = utf8_strcasestr("Hello WORLD", "world");

// Returns pointer to "WORLD" in the haystack

const char *found2 = utf8_strcasestr("Café français", "FRANÇAIS");

// Returns pointer to "français" (case-insensitive + accents)

utf8_strcasestr
const char * utf8_strcasestr(const char *haystack, const char *needle)
Case-insensitive substring search with full Unicode support.
Definition utf8.c:272

Uses utf8proc for Unicode case folding according to Unicode standard. This properly handles all Unicode scripts including Greek, Cyrillic, accented characters, and more.

Definition at line 272 of file utf8.c.

                                                                      {
  if (!haystack || !needle) {
    SET_ERRNO(ERROR_INVALID_PARAM, "invalid params");
    return NULL;
  }
 
  // Empty needle matches at start of haystack
  if (needle[0] == '\0') {
    return haystack;
  }
 
  // Get lengths
  size_t haystack_len = strlen(haystack);
  size_t needle_len = strlen(needle);
 
  if (needle_len > haystack_len) {
    return NULL;
  }
 
  // Case-fold both strings using utf8proc
  // UTF8PROC_CASEFOLD performs Unicode case folding
  // UTF8PROC_STABLE ensures stable output
  // UTF8PROC_COMPOSE normalizes composed characters
  utf8proc_option_t options = UTF8PROC_CASEFOLD | UTF8PROC_STABLE | UTF8PROC_COMPOSE;
 
  // Case-fold the needle (pattern to search for)
  utf8proc_uint8_t *needle_folded = NULL;
  utf8proc_ssize_t needle_folded_len =
      utf8proc_map((const utf8proc_uint8_t *)needle, (utf8proc_ssize_t)needle_len, &needle_folded, options);
 
  if (needle_folded_len < 0 || !needle_folded) {
    // Invalid UTF-8 in needle
    if (needle_folded) {
      free(needle_folded);
    }
    return NULL;
  }
 
  // Try each position in haystack
  const char *haystack_pos = haystack;
  while (*haystack_pos != '\0') {
    // Calculate remaining haystack length
    size_t remaining = haystack_len - (size_t)(haystack_pos - haystack);
 
    if (remaining < needle_len) {
      // Not enough characters left to match
      break;
    }
 
    // Case-fold the current haystack window
    utf8proc_uint8_t *haystack_folded = NULL;
    utf8proc_ssize_t haystack_folded_len =
        utf8proc_map((const utf8proc_uint8_t *)haystack_pos, (utf8proc_ssize_t)needle_len, &haystack_folded, options);
 
    if (haystack_folded_len >= 0 && haystack_folded) {
      // Compare case-folded strings
      if ((size_t)haystack_folded_len == (size_t)needle_folded_len &&
          memcmp(haystack_folded, needle_folded, (size_t)needle_folded_len) == 0) {
        // Match found!
        free(haystack_folded);
        free(needle_folded);
        return haystack_pos;
      }
      free(haystack_folded);
    }
 
    // Move to next UTF-8 character in haystack
    utf8proc_int32_t codepoint;
    utf8proc_ssize_t bytes = utf8proc_iterate((const utf8proc_uint8_t *)haystack_pos, -1, &codepoint);
    if (bytes <= 0) {
      // Invalid UTF-8, move by one byte
      haystack_pos++;
    } else {
      haystack_pos += bytes;
    }
  }
 
  free(needle_folded);
  return NULL;
}

References ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by grep_highlight_colored(), grep_should_output(), log_search_gather_and_filter_logs(), and log_search_get_match_info().

◆ utf8_to_codepoints()

size_t utf8_to_codepoints	(	const char *	str,
		uint32_t *	out_codepoints,
		size_t	max_codepoints
	)

#include <utf8.h>

Convert UTF-8 string to array of Unicode codepoints.

Parameters

str	UTF-8 string to convert (must not be NULL)
out_codepoints	Output array for decoded codepoints (must not be NULL)
max_codepoints	Maximum number of codepoints to decode

Returns: Number of codepoints decoded, or SIZE_MAX if invalid UTF-8 detected

Decodes a UTF-8 string into an array of Unicode codepoints (32-bit values). Stops when reaching end of string, hitting max_codepoints limit, or detecting invalid UTF-8.

Returns SIZE_MAX if invalid UTF-8 sequences are encountered during decoding.

Note: Returns 0 if str is NULL, out_codepoints is NULL, or max_codepoints is 0; Used by fuzzy matching (Levenshtein), Unicode algorithms, and validation; More efficient than calling utf8_decode multiple times in a loop

Example: // Compare two strings at codepoint level

uint32_t str1_codepoints[256];

uint32_t str2_codepoints[256];

size_t count1 = utf8_to_codepoints("café", str1_codepoints, 256);

size_t count2 = utf8_to_codepoints("cafe", str2_codepoints, 256);

if (count1 == SIZE_MAX || count2 == SIZE_MAX) {

return false; // Invalid UTF-8

}

// Now compare at codepoint level instead of bytes

for (size_t i = 0; i < count1 && i < count2; i++) {

if (str1_codepoints[i] != str2_codepoints[i]) {

// Different codepoint

}

}

utf8_to_codepoints
size_t utf8_to_codepoints(const char *str, uint32_t *out_codepoints, size_t max_codepoints)
Convert UTF-8 string to array of Unicode codepoints.
Definition utf8.c:185

Definition at line 185 of file utf8.c.

                                                                                            {
  if (!str || !out_codepoints || max_codepoints == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "str is NULL or out_codepoints is NULL or max_codepoints is 0");
    return 0;
  }
 
  size_t count = 0;
  const uint8_t *p = (const uint8_t *)str;
  while (*p && count < max_codepoints) {
    uint32_t codepoint;
    int decode_len = utf8_decode(p, &codepoint);
    if (decode_len < 0) {
      return -1; // SIZE_MAX - Invalid UTF-8
    }
    out_codepoints[count++] = codepoint;
    p += decode_len;
  }
  return count;
}

References ERROR_INVALID_PARAM, SET_ERRNO, and utf8_decode().

Referenced by levenshtein(), and validate_palette_chars().

◆ utf8_write_lowercase()

void utf8_write_lowercase	(	FILE *	output,
		const char *	text
	)

#include <utf8.h>

Write UTF-8 string to file with ASCII lowercase conversion.

Parameters

output	File pointer to write to (must not be NULL)
text	UTF-8 string to convert and write (may be NULL)

Writes text to output file, converting ASCII uppercase letters (A-Z) to lowercase (a-z) while preserving all UTF-8 multi-byte sequences unchanged. This is UTF-8 aware and does not modify non-ASCII characters.

Useful for terminal output where uppercase letters should be displayed as lowercase while preserving Unicode characters like emoji and accented letters.

Note: If text is NULL, function returns immediately without writing anything; Multi-byte UTF-8 sequences (e.g., emoji, CJK characters) are copied unchanged; Only ASCII uppercase (A-Z) is converted to lowercase (a-z); Continuation bytes in multi-byte sequences are never modified

Example: FILE *fp = fopen("output.txt", "w");

// ASCII text: converts uppercase

utf8_write_lowercase(fp, "HELLO World"); // Writes "hello world"

// UTF-8 emoji and non-ASCII: preserved

utf8_write_lowercase(fp, "CAFÉ 😀"); // Writes "café 😀" (emoji unchanged)

// Mixed case with non-ASCII

utf8_write_lowercase(fp, "HELLO 世界"); // Writes "hello 世界" (CJK unchanged)

fclose(fp);

utf8_write_lowercase
void utf8_write_lowercase(FILE *output, const char *text)
Write UTF-8 string to file with ASCII lowercase conversion.
Definition utf8.c:360

Converts ASCII uppercase to lowercase while preserving all UTF-8 multi-byte sequences unchanged. This ensures proper handling of emoji and non-ASCII characters while still performing ASCII case conversion.

Definition at line 360 of file utf8.c.

                                                          {
  if (!text) {
    return;
  }
 
  for (const unsigned char *p = (const unsigned char *)text; *p; p++) {
    // Check if this is the start of a multi-byte UTF-8 sequence
    if (*p >= 0xC0) {
      // Multi-byte UTF-8 character - copy as-is without modification
      fputc(*p, output);
      // Copy continuation bytes (0x80-0xBF)
      while (p[1] >= 0x80 && p[1] < 0xC0) {
        fputc(*++p, output);
      }
    } else if (*p >= 'A' && *p <= 'Z') {
      // ASCII uppercase - convert to lowercase
      fputc(*p + 32, output);
    } else {
      // ASCII lowercase or control character - copy as-is
      fputc(*p, output);
    }
  }
}

Referenced by __attribute__().

◆ validate_shell_safe()

bool validate_shell_safe	(	const char *	str,
		const char *	allowed_chars
	)

#include <string.h>

Validate that a string contains only safe characters for shell commands.

Parameters

str	String to validate (must not be NULL)
allowed_chars	Additional allowed characters (e.g., "-:_", can be NULL)

Returns: true if string is safe, false otherwise

Validates that a string contains only safe characters for use in shell commands. Rejects shell metacharacters that could be used for command injection or shell expansion.

REJECTED METACHARACTERS:

Control operators: ; & | $ ‘
Quote characters: " ’
Redirection: < >
Brackets: ( ) [ ] { }
Wildcards: * ?
Special: \ ! ~ # @

Note: The allowed_chars parameter adds exceptions to the safety check.; Empty strings are considered safe (returns true).; This function is essential for preventing command injection attacks.

Example: if (!validate_shell_safe(user_input, NULL)) {

// Reject unsafe input

}

validate_shell_safe
bool validate_shell_safe(const char *str, const char *allowed_chars)
Validate that a string contains only safe characters for shell commands.
Definition util/string.c:62

Definition at line 62 of file util/string.c.

                                                                     {
  if (!str) {
    return false;
  }
 
  // Shell metacharacters that are dangerous
  // ; & | $ ` \ " ' < > ( ) [ ] { } * ? ! ~ # @ space tab newline
  const char *dangerous = ";|$`\\\"'<>()[]{}*?!~#@ \t\n\r";
 
  // First pass: validate UTF-8 encoding
  if (!utf8_is_valid(str)) {
    return false;
  }
 
  // Second pass: validate each character for shell safety
  // Convert to codepoints and check only ASCII range for dangerous characters
  // (non-ASCII characters are allowed by default)
  const uint8_t *p = (const uint8_t *)str;
  while (*p) {
    uint32_t codepoint;
    int decode_len = utf8_decode(p, &codepoint);
    if (decode_len < 0) {
      return false; // Should not happen after utf8_is_valid check
    }
 
    // Only validate ASCII range where shell metacharacters exist
    // Non-ASCII characters (codepoint > 127) are allowed
    if (codepoint <= 127) {
      unsigned char c = (unsigned char)codepoint;
 
      // Allow ASCII alphanumeric characters
      if (isalnum(c)) {
        p += decode_len;
        continue;
      }
 
      // Check if character is in allowed_chars list
      if (allowed_chars) {
        bool is_allowed = false;
        for (size_t j = 0; allowed_chars[j] != '\0'; j++) {
          if (c == (unsigned char)allowed_chars[j]) {
            is_allowed = true;
            break;
          }
        }
        if (is_allowed) {
          p += decode_len;
          continue;
        }
      }
 
      // Check if character is dangerous
      bool is_dangerous = false;
      for (size_t j = 0; dangerous[j] != '\0'; j++) {
        if (c == (unsigned char)dangerous[j]) {
          is_dangerous = true;
          break;
        }
      }
      if (is_dangerous) {
        return false;
      }
    }
 
    p += decode_len;
  }
 
  return true;
}

References utf8_decode(), and utf8_is_valid().

Referenced by gpg_get_public_key().

Files

Data Structures

Macros

Enumerations

Functions

Detailed Description

CORE FEATURES:

HARDWARE ACCELERATION:

SOFTWARE FALLBACK:

PERFORMANCE:

CORE FEATURES:

TERMINAL CHARACTER CORRECTION:

ASPECT RATIO CALCULATIONS:

CORE FEATURES:

PLATFORM SUPPORT:

CORE FEATURES:

UNALIGNED ACCESS:

CORE FEATURES:

BYTE FORMATTING:

CORE FEATURES:

IP ADDRESS FORMATS:

BRACKET NOTATION:

CORE FEATURES:

CORE FEATURES:

USAGE:

CORE FEATURES:

MOTIVATION:

USAGE:

CORE FEATURES:

PROTOCOL MESSAGE FORMATS:

VALIDATION:

Core Features

Path Expansion

Configuration Directories

CORE FEATURES:

SHELL ESCAPING:

SHELL METACHARACTERS:

Utility Functions

Overview

Utility Modules

CRC32 Checksums

Aspect Ratio

IP Address Utilities

UTF-8 String Handling

Path Utilities

String Utilities

Parsing Utilities

Format Utilities

Mathematical Utilities

Performance Notes

Best Practices

Macro Definition Documentation

◆ asciichat_crc32

◆ FNV1A_32_HASH

◆ FNV1A_32_MASK

◆ FNV1A_32_OFFSET_BASIS

◆ FNV1A_32_PRIME

◆ FNV1A_INIT

◆ MAX_PATH_BASES

◆ PASSWORD_MAX_LEN

◆ PATH_COMPONENT_DOT

◆ PATH_COMPONENT_DOTDOT

◆ PATH_DRIVE_SEPARATOR

◆ PATH_TILDE

◆ ROUND

◆ SIZE_ADD_SAFE

◆ SIZE_MUL_SAFE

Enumeration Type Documentation

◆ path_role_t

Function Documentation

◆ __isoc23_scanf()

◆ __isoc23_wcstol()

◆ __isoc23_wscanf()

◆ arc4random_buf()

◆ asciichat_crc32_hw()

◆ asciichat_crc32_sw()

◆ aspect_ratio()

◆ aspect_ratio2()

◆ calculate_fit_dimensions_pixel()

◆ canonicalize_ipv6()