string manipulation, file handling, and error reporting. More...

Functions
unsigned long	a_to_ul (const char *str)
	Converts a string to an unsigned long long integer, with support for suffixes K, M, and G for kilobytes, megabytes, and gigabytes respectively.
int	a_toi (char s, bool a_toi_error)
	a safer alternative to atoi() for converting ASCII strings to integers.
bool	base_name (char buf, char path)
	Returns the base name of a file specification.
size_t	canonicalize_file_spec (char *spec)
	Removes quotes and trims at first space.
bool	chrep (char *s, char old_chr, char new_chr)
	Replaces all occurrences of old_chr in s with new_chr in place.
int	destroy_argv (int argc, char **argv)
	Deallocates memory allocated for argument strings in argv.
bool	dir_name (char buf, char path)
	Returns the directory name of a file specification.
bool	expand_tilde (char *str, int path_maxlen)
	Replaces "~/" in string with the user's home directory.
char *	fdname (int fd, char *out_path)
	Retrieves the file path associated with a given file descriptor.
bool	file_spec_name (char file_name, char fs)
	extracts the file name component of a file specification
bool	file_spec_path (char fp, char fs)
	extracts the path component of a file specification
char *	format_local_timestamp (time_t t, char *buf, size_t n)
	Formats a time_t as an ISO 8601 string in local time.
bool	get_argp_doc_by_name (char comment, const struct argp_option options, const char *key_name)
	Retrieves the documentation string for a given key name from an argp options array.
char *	get_ip_addresses (char *ip_str, int maxlen)
	Retrieves the IP addresses of the local machine and formats them into a string.
char *	get_local_timestamp ()
	Returns the current local time as an ISO 8601 formatted string.
char *	get_user_str (char *user_str, size_t maxlen)
	Retrieves the current user's name and UID, and formats it into a string.
bool	is_directory (const char *path)
	Checks if the given path is a directory.
bool	is_hex_str (char *str, int len)
	Validates that a string consists of exactly len hexadecimal digits.
bool	is_newer (char control, char fut)
	Checks if the file specified by "fut" is newer than the file specified by "control".
bool	is_symlink_to_dir (const char *path)
	Checks if the given path is a symbolic link to a directory.
bool	is_valid_regex (const char *pattern)
	Checks if the given regular expression pattern is valid.
char *	iso8601_time (char buf, int n, time_t t, bool local)
	Formats a struct tm as an ISO 8601 string.
bool	locate_file_in_path (char file_spec, char file_name)
	Locates a file in the system PATH.
bool	mk_dir (char *dir)
	If directory doesn't exist, make it.
bool	normalize_file_spec (char *fs)
	replace backslashes with forward lashes
void	open_cmenu_log ()
	Open new C-Menu log file.
bool	parse_local_timestamp (const char s, time_t out)
	Parses an ISO 8601 timestamp string in local time and converts it to time_t.
char *	rep_substring (const char org_s, const char tgt_s, const char *rep_s)
	Replace all occurrences of "tgt_s" in "org_s" with "rep_s".
size_t	ssnprintf (char buf, size_t buf_size, const char format,...)
	ssnprintf was designed to be a safer alternative to snprintf.
bool	str_subc (char d, char s, char ReplaceChr, char *Withstr, int l)
	Replaces "ReplaceChr" in "s" with "Withstr" in "d" won't copy more than "l" bytes to "d" Replaces all occurrences of a character in a string with another string, copying the result to a destination buffer.
int	str_to_args (char *argv, char arg_str, int max_args)
	Converts a string into an array of argument strings.
double	str_to_double (char *s)
	converts string to double
bool	str_to_lower (char *s)
	Converts a string to lowercase.
bool	str_to_upper (char *s)
	Converts a string to uppercase.
size_t	strip_ansi (char d, char s)
	Strips ANSI SGR escape sequences (ending in 'm') from string s to d.
bool	strip_quotes (char *s)
	removes leading and trailing double quotes if present
bool	stripz_quotes (char *s)
	removes leading and trailing double quotes if present
size_t	strnlf (char *s, size_t max_len)
	terminates string with line feed
size_t	strnz (char *s, size_t max_len)
	terminates string at New Line, Carriage Return, or max_len
size_t	strnz__cat (char d, const char s, size_t max_len)
	safer alternative to strncat
size_t	strnz__cpy (char d, const char s, size_t max_len)
	safer alternative to strncpy
char *	strnz_dup (char *s, size_t l)
	Allocates memory for and duplicates string s up to length l or until line feed or carriage return.
size_t	strz (char *s)
	Terminates string at new line or carriage return.
size_t	trim (char *s)
	Trims leading and trailing spaces from string s in place.
bool	trim_ext (char buf, char filename)
	trims the file extension from "filename" and copies the result to "buf"
bool	trim_path (char *dir)
	Trims trailing spaces and slashes from directory path in place.
void	ui_rect_set (UiRect *r, int y, int x, int h, int w)
	Set the properties of a UiRect structure.
bool	unstr_hex_clr (char dst, char str)
	Validates that a string is a hex color code in the format "#RRGGBB".
bool	verify_dir (char *spec, int imode)
	Verifies that the directory specified by "spec" exists and is accessible with the permissions specified by "imode".
bool	verify_file (char *in_spec, int imode)
	Verifies that the file specified by "in_spec" exists and is accessible with the permissions specified by "imode".
int	wccp_to_str (wchar_t cp, uint8_t *buffer)
	Converts a Unicode code point to a UTF-8 encoded string.
void	write_cmenu_log (char *msg)
	Write message to C-Menu log file with timestamp.
void	write_cmenu_log_nt (char *msg)
	Write message to C-Menu log file without timestamp.

Detailed Description

string manipulation, file handling, and error reporting.

These functions provide common operations such as trimming strings, converting case, safely copying and concatenating strings, verifying file and directory access, and locating files in the system PATH. They are designed to be robust and handle edge cases gracefully, making them useful for a wide range of applications.

Function Documentation

◆ a_to_ul()

unsigned long a_to_ul ( const char * str )

Converts a string to an unsigned long long integer, with support for suffixes K, M, and G for kilobytes, megabytes, and gigabytes respectively.

Parameters

str	- string to convert

Returns: converted unsigned long long value, or 0 if str is nullptr, empty, or invalid

This function is useful for parsing human-readable file sizes or memory sizes that may include suffixes to indicate the scale of the value. If the string is invalid (e.g., contains non-numeric characters other than the optional suffix), this function returns 0. The caller must ensure that the input string is a valid representation of an unsigned long long integer with an optional suffix before calling this function.

Definition at line 793 of file futil.c.

                                       {
    char *endptr;
    unsigned long value = (unsigned long)strtoull(str, &endptr, 10);
    if (endptr == str)
        return 0;
    switch (tolower(*endptr)) {
    case 'g':
        return value * 1024ULL * 1024ULL * 1024ULL;
    case 'm':
        return value * 1024ULL * 1024ULL;
    case 'k':
        return value * 1024ULL;
    default:
        return value;
    }
}

◆ a_toi()

int a_toi	(	char *	s,
		bool *	a_toi_error )

a safer alternative to atoi() for converting ASCII strings to integers.

Parameters

s	is the input string
a_toi_error	is a pointer to a boolean that will be set to true if an error occurs during conversion, or false if the conversion is successful.

Returns: converted integer value, or -1 if an error occurs

Accepts positive integers only. Sets a_toi_error to (-1) on error

Definition at line 769 of file futil.c.

                                      {
    int rc = -1;
    *a_toi_error = false;
    errno = 0;
    if (s && *s != 0)
        rc = (int)strtol(s, nullptr, 10);
    if (rc < 0 || errno) {
        rc = -1;
        *a_toi_error = true;
    }
    return rc;
}

Referenced by parse_ansi_str().

Here is the caller graph for this function:

◆ base_name()

bool base_name	(	char *	buf,
		char *	path )

Returns the base name of a file specification.

Parameters

buf	- buffer to receive result
path	- file specification

Returns: true if successful

Note: The caller is responsible for ensuring that "buf" has enough space to receive the result.

Definition at line 1123 of file futil.c.

                                      {
    if (!path || !*path || !buf)
        return false;
    char *s = path;
    char *d = buf;
    *d = '\0';
    while (*s) {
        if (*s == '/' || *s == '\\') {
            d = buf;
        } else {
            *d++ = *s;
        }
        s++;
    }
    *d = '\0';
    if (d == buf)
        return false;
    return true;

Referenced by build_prompt(), exec_objects(), form_exec_receiver(), form_process(), init_form_files(), init_pick_files(), main(), and view_init_input().

Here is the caller graph for this function:

◆ canonicalize_file_spec()

size_t canonicalize_file_spec ( char * spec )

Removes quotes and trims at first space.

Parameters

spec	- file specification to canonicalize

Returns: length of resulting string

Definition at line 1341 of file futil.c.

                                          {
    if (spec == nullptr || *spec == '\0')
        return 0;
    char tmp_s[MAXLEN];
    char *s;
    s = spec;
    char *d;
    d = tmp_s;
    int l = 0;
    while (*s != '\0') {
        if (*s == ' ')
            break;
        if (*s == '\"' || *s == '\'') {
            s++;
            continue;
            ;
        }
        *d++ = *s++;
        l++;
    }
    *d = '\0';
    strnz__cpy(spec, tmp_s, MAXLEN - 1);
    l = strlen(spec);
    return l;

References strnz__cpy().

Referenced by locate_file_in_path(), verify_file(), and verify_spec_arg().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ chrep()

bool chrep	(	char *	s,
		char	old_chr,
		char	new_chr )

Replaces all occurrences of old_chr in s with new_chr in place.

Parameters

s	- string to modify
old_chr	- character to replace
new_chr	- character to insert

Returns: true if successful or false if string s is null

Definition at line 750 of file futil.c.

                                                {
    if (s == nullptr)
        return false;
    while (*s != '\0') {
        if (*s == old_chr)
            *s = new_chr;
        s++;
    }
    return true;
}

Referenced by parse_menu_description().

Here is the caller graph for this function:

◆ destroy_argv()

int destroy_argv	(	int	argc,
		char **	argv )

Deallocates memory allocated for argument strings in argv.

Parameters

argc	- count of allocated vectors in argv
argv	- array of pointers to arguments

Note: the caller must ensure that argc accurately reflects the number of allocated strings in argv, and that argv is not null. After calling this function, the pointers in argv will be set to nullptr to prevent dangling pointers.

Definition at line 494 of file futil.c.

                                        {
    for (int i = 0; i < argc; i++) {
        if (argv[i] != nullptr) {
            free(argv[i]);
            argv[i] = nullptr;
        }
    }
    argc = 0;
    return argc;
}

Referenced by destroy_init(), destroy_view(), display_pick_help(), enter_file_spec(), exec_objects(), form_engine(), form_exec_receiver(), form_process(), init_pick(), menu_cmd_processor(), new_pick_view(), parse_opt_args(), view_display_help(), and view_init_input().

Here is the caller graph for this function:

◆ dir_name()

bool dir_name	(	char *	buf,
		char *	path )

Returns the directory name of a file specification.

Parameters

buf	- buffer to receive result
path	- file specification

Returns: true if successful

Note: The caller is responsible for ensuring that "buf" has enough space to receive the result.

Definition at line 1149 of file futil.c.

                                     {
    if (!path || !*path || !buf)
        return false;
    char tmp_str[MAXLEN];
    strnz__cpy(tmp_str, path, MAXLEN);
    char *s = tmp_str;
    while (*s++)
        ;
    while (tmp_str < --s) {
        if (*s == '/' || *s == '\\') {
            *s = '\0';
            break;
        }
    }
    while (tmp_str < --s && (*s == '/' || *s == '\\'))
        *s = '\0';
    char *d = buf;
    *d = '\0';
    s = tmp_str;
    while (*s) {
        *d++ = *s++;
    }
    *d = '\0';
    if (d == buf)
        return false;
    return true;

References strnz__cpy().

Here is the call graph for this function:

◆ expand_tilde()

bool expand_tilde	(	char *	str,
		int	path_maxlen )

Replaces "~/" in string with the user's home directory.

Parameters

str	- string to modify
path_maxlen	- maximum length of resulting string

Returns: true if successful, false if str is nullptr or empty

Definition at line 970 of file futil.c.

                                              {
    if (str == nullptr || *str == '\0')
        return false;
    const char tgt[3] = "~/";
    char path[MAXLEN];
    char *e = getenv("HOME");
    strnz__cpy(path, e, MAXLEN - 1);
    strnz__cat(path, "/", MAXLEN - 1);
    char *tmp;
    tmp = rep_substring(str, tgt, path);
    strnz__cpy(str, tmp, path_maxlen - 1);
    free(tmp);
    return true;

References rep_substring(), strnz__cat(), and strnz__cpy().

Referenced by enter_file_spec(), init_form_files(), init_pick_files(), init_view_files(), main(), mapp_initialization(), mk_dir(), process_config_file(), process_config_files(), read_theme(), verify_dir(), verify_file(), verify_spec_arg(), and view_init_input().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fdname()

char * fdname	(	int	fd,
		char *	out_path )

Retrieves the file path associated with a given file descriptor.

Parameters

fd	- file descriptor
out_path	- buffer to receive the file path

Returns: 0 on success, -1 on failure

This function uses the /proc filesystem to read the symbolic link corresponding to the file descriptor. It constructs the path to the symbolic link in /proc/self/fd/ and uses readlink to retrieve the actual file path. The caller must ensure that out_path has enough space to hold the resulting path. If readlink fails, this function returns -1 and does not modify out_path.

Definition at line 1054 of file futil.c.

                                     {
    char proc_path[MAXLEN];
 
    snprintf(proc_path, sizeof(proc_path), "/proc/self/fd/%d", fd);
    ssize_t len = readlink(proc_path, out_path, MAXLEN - 1);
    if (len == -1)
        return nullptr;
    out_path[len] = '\0';
    return out_path;

Referenced by stdio_fdnames().

Here is the caller graph for this function:

◆ file_spec_name()

bool file_spec_name	(	char *	file_name,
		char *	fs )

extracts the file name component of a file specification

Parameters

file_name	- name component to return
fs	- full file specification

Note: The caller is responsible for ensuring that "file_name" has enough space to receive the result.

Definition at line 897 of file futil.c.

                                               {
    if (fs == nullptr || *fs == '\0' || file_name == nullptr) {
        if (file_name != nullptr)
            *file_name = '\0';
        return false;
    }
    char *d, *l, *s;
    l = nullptr;
    s = fs;
    while (*s != '\0') {
        if (*s == '/')
            l = s;
        s++;
    }
    if (l == nullptr)
        s = fs;
    else
        s = ++l;
    d = file_name;
    while (*s != '\0')
        *d++ = *s++;
    *d = '\0';
    return true;

◆ file_spec_path()

bool file_spec_path	(	char *	fp,
		char *	fs )

extracts the path component of a file specification

Parameters

fp	- path component to return
fs	- full file specification

Returns: true if successful

Note: The caller is responsible for ensuring that "fp" has enough space to receive the result.

Definition at line 870 of file futil.c.

                                        {
    if (fs == nullptr || *fs == '\0' || fp == nullptr) {
        if (fp != nullptr)
            *fp = '\0';
        return false;
    }
    char *d, *l, *s;
    s = fp;
    d = fs;
    l = nullptr;
    while (*s != '\0') {
        if (*s == '/')
            l = d;
        *d++ = *s++;
    }
    if (l == nullptr)
        *fp = '\0'; // no slash, so no path
    else
        *l = '\0';
    return true;

◆ format_local_timestamp()

char * format_local_timestamp	(	time_t	t,
		char *	buf,
		size_t	n )

Formats a time_t as an ISO 8601 string in local time.

Parameters

t	- time to format
buf	- buffer to receive formatted string
n	- size of buffer

Returns: pointer to buf

Note: The caller is responsible for ensuring that buf has enough space to hold the resulting string. The ISO 8601 format produced is "YYYY-MM-DDTHH:MM:SS" followed by the local time zone offset (e.g., "+hhmm" or "-hhmm"). This function uses strftime internally, so the actual format may vary based on the implementation of strftime and the locale settings.

Definition at line 303 of file futil.c.

                                                            {
    struct tm tmv;
    localtime_r(&t, &tmv);
    strftime(buf, n, "%Y-%m-%dT%H:%M:%S", &tmv);
    return buf;
}

Referenced by debug_out(), and get_local_timestamp().

Here is the caller graph for this function:

◆ get_argp_doc_by_name()

bool get_argp_doc_by_name	(	char *	comment,
		const struct argp_option *	options,
		const char *	key_name )

Retrieves the documentation string for a given key name from an argp options array.

Parameters

comment	- buffer to receive the documentation string
options	- array of argp_option structures to search
key_name	- the long option name or short option character

Definition at line 176 of file futil.c.

                                                {
    for (size_t i = 0; options[i].name != NULL || options[i].key != 0; i++) {
        // Skip purely cosmetic header/group entries in argp
        if (options[i].name == NULL && options[i].doc != NULL &&
            options[i].key == 0) {
            continue;
        }
 
        // 1. Check against the long option name (e.g., "verbose")
        if (options[i].name && strcmp(options[i].name, key_name) == 0) {
            strnz__cpy(comment, options[i].doc, MAXLEN - 1);
            return true;
        }
 
        // 2. Check against the short option key character (e.g., 'v')
        if (options[i].key > 0 && options[i].key < 127) {
            char short_str[2] = {(char)options[i].key, '\0'};
            if (strcmp(short_str, key_name) == 0) {
                strnz__cpy(comment, options[i].doc, MAXLEN - 1);
                return true;
            }
        }
    }
    return false; // Key not found in the argp structure
}

References strnz__cpy().

Referenced by print_argp_doc().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_ip_addresses()

char * get_ip_addresses	(	char *	ip_str,
		int	maxlen )

Retrieves the IP addresses of the local machine and formats them into a string.

Parameters

ip_str	- buffer to receive formatted string of IP addresses
maxlen	- size of buffer

Returns: pointer to ip_str containing the formatted IP addresses, or nullptr if an error occurs

This function uses getifaddrs to retrieve a linked list of network interfaces on the local machine. It iterates through the list and checks for interfaces with IPv4 addresses (AF_INET). For each valid interface, it converts the binary IP address to a human-readable string using inet_ntop and appends it to the provided buffer in the format "[interface-name-IP-address]". Multiple interfaces are separated by commas. The caller must ensure that ip_str has enough space to hold the resulting string. If getifaddrs fails, this function returns nullptr and does not modify the buffer.

Definition at line 354 of file futil.c.

                                                 {
    char tmp_str[MAXLEN];
    struct ifaddrs *ifaddr, *ifa;
    char host[INET_ADDRSTRLEN];
    bool comma_before = false;
    // getifaddrs returns a linked list of network interface structures
    if (getifaddrs(&ifaddr) == -1) {
        perror("getifaddrs");
        exit(EXIT_FAILURE);
    }
    ip_str[0] = '\0';
    // Walk through the linked list
    for (ifa = ifaddr; ifa != NULL; ifa = ifa->ifa_next) {
        if (ifa->ifa_addr == NULL)
            continue;
        // Check for IPv4 addresses
        if (ifa->ifa_addr->sa_family == AF_INET) {
            struct sockaddr_in *pAddr = (struct sockaddr_in *)ifa->ifa_addr;
 
            // Convert binary IP to human-readable string
            inet_ntop(AF_INET, &pAddr->sin_addr, host, INET_ADDRSTRLEN);
 
            if (comma_before)
                snprintf(tmp_str, MAXLEN - 1, ",[%s-%s]", ifa->ifa_name, host);
            else
                snprintf(tmp_str, MAXLEN - 1, "[%s-%s]", ifa->ifa_name, host);
            strnz__cat(ip_str, tmp_str, maxlen - 1);
            comma_before = true;
        }
    }
    freeifaddrs(ifaddr); // Clean up the memory allocated by getifaddrs
    return ip_str;
}

References strnz__cat().

Referenced by debug_out().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_local_timestamp()

char * get_local_timestamp ( )

Returns the current local time as an ISO 8601 formatted string.

Returns: pointer to static buffer containing the current local timestamp in ISO 8601 format

Note: The returned string is stored in a static buffer, so it will be overwritten by subsequent calls to this function. The format of the returned string is "YYYY-MM-DDTHH:MM:SS" followed by the local time zone offset (e.g., "+hhmm" or "-hhmm"). This function uses the current system time and formats it using strftime internally, so the actual format may vary based on the implementation of strftime and the locale settings.

Definition at line 314 of file futil.c.

                            {
    static char buf[32];
    time_t t = time(NULL);
    format_local_timestamp(t, buf, sizeof buf);
    return buf;
}

References format_local_timestamp().

Referenced by debug_out().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_user_str()

char * get_user_str	(	char *	user_str,
		size_t	maxlen )

Retrieves the current user's name and UID, and formats it into a string.

Parameters

user_str	- buffer to receive formatted string
maxlen	- size of buffer

Returns: pointer to user_str containing the formatted user information, or nullptr if an error occurs

This function uses getuid to retrieve the current user's UID, then uses getpwuid to get the corresponding passwd structure, which contains the user's name. It formats the user's name and UID into the provided buffer in the format "User: username (uid)\n". The caller must ensure that user_str has enough space to hold the resulting string. If getpwuid fails (e.g., if the UID does not exist), this function returns nullptr and does not modify the buffer.

Definition at line 327 of file futil.c.

                                                  {
    uid_t uid = getuid();
    struct passwd *pw = getpwuid(uid);
    if (pw == NULL)
        return nullptr;
    ssnprintf(user_str, maxlen - 1, "%s (%u)", pw->pw_name, (unsigned int)uid);
    return user_str;
}

References ssnprintf().

Referenced by debug_out().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_directory()

bool is_directory ( const char * path )

Checks if the given path is a directory.

Parameters

path	- path to check

Returns: 0 exists 1 is a directory -1 does not exist

Definition at line 1372 of file futil.c.

                                    {
    struct stat statbuf;
    if (stat(path, &statbuf) == 0)
        if (S_ISDIR(statbuf.st_mode))
            return true;
    return false;

Referenced by main().

Here is the caller graph for this function:

◆ is_hex_str()

bool is_hex_str	(	char *	str,
		int	len )

Validates that a string consists of exactly len hexadecimal digits.

Parameters

str	- input string to validate
len	- expected number of hexadecimal digits

Returns: true if str is a valid hex string of the specified length, false otherwise

This function checks that the input string contains only hexadecimal characters (0-9, A-F, a-f) and that the total number of hex digits matches the specified length. If the input string is valid, it returns true; otherwise, it returns false. The caller must ensure that the input string is not null and has at least one character before calling this function.

Definition at line 209 of file futil.c.

                                    {
    char *s = str;
    char *e;
    if (s == NULL || *s == '\0')
        return false;
    e = (s + len + 1);
    while (s < e && *s != '\0') {
        if (!isxdigit(*s)) {
            return false;
        }
        s++;
    }
    if ((int)(s - str) != len)
        return false;
    return true;
}

◆ is_newer()

bool is_newer	(	char *	control,
		char *	fut )

Checks if the file specified by "fut" is newer than the file specified by "control".

Parameters

control	- path to the control file
fut	- path to the file to compare against the control file

Returns: true if "fut" is newer than "control", false otherwise

This function uses the stat system call to retrieve the modification times of both files. It compares the modification time of "fut" with that of "control" and returns true if "fut" has a more recent modification time. If either file cannot be accessed or if any error occurs during the stat calls, this function returns false. The caller must ensure that both file paths are valid and that the files exist before calling this function.

Definition at line 160 of file futil.c.

                                        {
    // is fut newer than control?
    struct stat control_st, fut_st;
    if (!stat(control, &control_st))
        if (!lstat(fut, &fut_st))
            if (fut_st.st_mtime > control_st.st_mtime)
                return true;
    return false;
}

◆ is_symlink_to_dir()

bool is_symlink_to_dir ( const char * path )

Checks if the given path is a symbolic link to a directory.

Parameters

path	- path to check

Returns: 0 exists 1 symbolic link to a directory -1 does not exist or not a symbolic link to a directory

Definition at line 1385 of file futil.c.

                                         {
    struct stat link_stat;
    struct stat target_stat;
 
    if (lstat(path, &link_stat) == 0)
        if (S_ISLNK(link_stat.st_mode))
            if (stat(path, &target_stat) == 0)
                if (S_ISDIR(target_stat.st_mode))
                    return true; // symbolic link to a directory
    return false;

Referenced by main().

Here is the caller graph for this function:

◆ is_valid_regex()

bool is_valid_regex ( const char * pattern )

Checks if the given regular expression pattern is valid.

Parameters

pattern - regular expression pattern to check

Returns: true if the pattern is valid, false otherwise

Definition at line 1400 of file futil.c.

                                         {
    regex_t regex;
    int ret = regcomp(&regex, pattern, REG_EXTENDED);
    regfree(&regex);
    if (ret == 0)
        return true;
    return false;

Referenced by main().

Here is the caller graph for this function:

◆ iso8601_time()

char * iso8601_time	(	char *	buf,
		int	n,
		time_t *	t,
		bool	local )

Formats a struct tm as an ISO 8601 string.

Parameters

buf	- buffer to receive formatted string
n	- size of buffer
t	- struct tm to format
local	- if true, include local time zone offset; if false, use 'Z' for UTC

Returns: pointer to buf

Note: The caller is responsible for ensuring that buf has enough space to hold the resulting string. The ISO 8601 format produced is "YYYY-MM-DDTHH:MM:SSZ" for UTC or "YYYY-MM-DDTHH:MM:SS±hhmm" for local time. This function uses strftime internally, so the actual format may vary based on the implementation of strftime and the locale settings.

Definition at line 264 of file futil.c.

                                                            {
    struct tm *tp = local ? localtime(t) : gmtime(t);
    if (local) {
        strftime(buf, n, "%Y-%m-%dT%H:%M:%S%z", tp);
    } else {
        strftime(buf, n, "%Y-%m-%dT%H:%M:%SZ", tp);
    }
    return buf;
}

◆ locate_file_in_path()

bool locate_file_in_path	(	char *	file_spec,
		char *	file_name )

Locates a file in the system PATH.

Parameters

file_spec	- buffer to receive located file specification
file_name	- name of file to locate

Returns: true if file is located

Note: file_spec must be large enough to receive the result

Definition at line 1287 of file futil.c.

                                                           {
    if (file_name == nullptr || *file_name == '\0' || file_spec == nullptr)
        return false;
    char path[MAXLEN];
    char ifn[MAXLEN];
    char *p, *fnp, *dir;
 
    canonicalize_file_spec(file_name);
    strnz__cpy(ifn, file_name, MAXLEN - 1);
    fnp = ifn;
    while (*fnp && *fnp != '/')
        fnp++;
    if (*fnp == '/')
        return false;
    if ((p = getenv("PATH")) == nullptr)
        return false;
    strnz__cpy(path, p, MAXLEN - 1);
    dir = strtok(path, ":");
    while (dir != nullptr) {
        strnz__cpy(file_spec, dir, MAXLEN - 1);
        strnz__cat(file_spec, "/", MAXLEN - 1);
        strnz__cat(file_spec, file_name, MAXLEN - 1);
        if (access(file_spec, F_OK) == 0) {
            return true;
        }
        dir = strtok(nullptr, ":");
    }
    return false;

References canonicalize_file_spec(), strnz__cat(), and strnz__cpy().

Referenced by init_form_files(), init_pick_files(), and verify_spec_arg().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mk_dir()

bool mk_dir ( char * dir )

If directory doesn't exist, make it.

Parameters

dir	directory name

Returns: true if directory now exists or false otherwise

Directory does not exist and unable to create

Definition at line 1320 of file futil.c.

                       {
    expand_tilde(dir, MAXLEN - 1);
    if (!verify_dir(dir, S_WCOK | S_QUIET)) {
        if (!mkdir(dir, 0755)) {
            ssnprintf(em0, MAXLEN - 1, "%s, line: %d", __FILE__, __LINE__ - 2);
            strnz__cpy(em1, "mkdir ", MAXLEN - 1);
            strnz__cat(em1, dir, MAXLEN - 1);
            strnz__cat(em1, " failed", MAXLEN - 1);
            strerror_r(errno, em2, MAXLEN - 1);
            display_error(em0, em1, em2, nullptr);
            return false;
        }
        return true;
    }
    return true;

References display_error(), em0, em1, em2, expand_tilde(), ssnprintf(), strnz__cat(), strnz__cpy(), and verify_dir().

Referenced by enter_file_spec().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ normalize_file_spec()

bool normalize_file_spec ( char * fs )

replace backslashes with forward lashes

Parameters

fs	- file specification to normalize

Returns: true if successful, false if fs is nullptr or empty

Definition at line 853 of file futil.c.

                                   {
    if (fs == nullptr || *fs == '\0')
        return false;
    while (*fs != '\0') {
        if (*fs == '\\')
            *fs = '/';
        fs++;
    }
    return true;

◆ open_cmenu_log()

void open_cmenu_log ( )

Open new C-Menu log file.

Definition at line 1667 of file futil.c.

                      {
    char ttyname[MAXLEN];
    char cmenu_user[MAXLEN];
    char *p;
    cmenu_log_fd = open("/tmp/cmenu.log", O_WRONLY | O_CREAT | O_TRUNC,
                        S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP);
    p = getenv("USER");
    strnz__cpy(cmenu_user, p, MAXLEN - 1);
    if (ttyname_r(STDERR_FILENO, ttyname, sizeof(ttyname)) == 0)
        strnz__cpy(em0, ttyname, MAXLEN - 1);
    ssnprintf(em0, MAXLEN - 1, "C-Menu started by user '%s' on terminal '%s'\n",
              cmenu_user, ttyname);
    write_cmenu_log(em0);

References cmenu_log_fd, em0, ssnprintf(), strnz__cpy(), and write_cmenu_log().

Here is the call graph for this function:

◆ parse_local_timestamp()

bool parse_local_timestamp	(	const char *	s,
		time_t *	out )

Parses an ISO 8601 timestamp string in local time and converts it to time_t.

Parameters

s	- ISO 8601 timestamp string to parse (e.g., "2024-06-01T12:34:56")
out	- pointer to time_t variable to receive the result

Returns: true if parsing and conversion were successful, false otherwise

This function expects the input string to be in the format "YYYY-MM-DDTHH:MM:SS" representing local time. It uses strptime to parse the string into a struct tm, then uses mktime to convert it to time_t. The caller must ensure that the input string is properly formatted and represents a valid date and time. If the input string is invalid or if any error occurs during parsing or conversion, this function returns false and does not modify the output variable.

Definition at line 280 of file futil.c.

                                                       {
    struct tm tmv;
    memset(&tmv, 0, sizeof tmv);
    tmv.tm_isdst = -1;
 
    if (strptime(s, "%Y-%m-%dT%H:%M:%S", &tmv) == NULL)
        return false;
 
    time_t t = mktime(&tmv);
    if (t == (time_t)-1)
        return false;
 
    *out = t;
    return true;
}

◆ rep_substring()

char * rep_substring	(	const char *	org_s,
		const char *	tgt_s,
		const char *	rep_s )

Replace all occurrences of "tgt_s" in "org_s" with "rep_s".

Parameters

org_s	- original string
tgt_s	- target substring to replace
rep_s	- replacement substring

Returns: A pointer to the newly allocated string with replacements or a copy of the replacement string if original string is the same as target string This is a special case that allows for replacing the entire original string. If any parameter is nullptr, the function returns nullptr. If "tgt_s" is not found in "org_s", the function returns a copy of "org_s". If target substring is not found the function returns a copy of the original string.

Note: allocates memory for the return value, so the caller is responsible for freeing this memory when it is no longer needed to avoid memory leaks. Does not modify the original string "org_s".; Assumes that "tgt_s" and "rep_s" are null-terminated strings. If they are not, the behavior is undefined.; Does not perform any bounds checking on the input strings, so it is the caller's responsibility to ensure that they are valid and that the resulting string does not exceed available memory.; Uses the standard library functions strlen, strstr, malloc, and strcpy, which may have their own limitations and behaviors that the caller should be aware of.; Does not handle overlapping occurrences of "tgt_s" in "org_s". If "tgt_s" can overlap with itself in "org_s", the behavior may be unexpected. The caller should ensure that "tgt_s" does not contain overlapping patterns to avoid this issue.; Does not handle cases where "tgt_s" is a substring of "rep_s", which could lead to unintended consequences if "tgt_s" appears in "rep_s". The caller should ensure that "tgt_s" and "rep_s" are distinct to avoid this issue.

Definition at line 1440 of file futil.c.

                                                                             {
    if (org_s == nullptr || tgt_s == nullptr || rep_s == nullptr)
        return nullptr;
    if (*org_s == '\0' || *tgt_s == '\0' || *rep_s == '\0')
        return nullptr;
    if (strstr(org_s, tgt_s) == nullptr)
        return strdup(org_s);
    if (strstr(rep_s, tgt_s) != nullptr)
        return nullptr;
    if (tgt_s == rep_s || tgt_s == org_s || rep_s == org_s)
        return strdup(org_s);
    if (strcmp(org_s, tgt_s) == 0)
        return strdup(rep_s);
    char *out_s, *ip, *tmp;
    int tgt_l = strlen(tgt_s);
    int rep_l = strlen(rep_s);
    int head_l;
    int n = 0;
    ip = (char *)org_s;
    while ((tmp = strstr(ip, tgt_s)) != nullptr) {
        n++;
        ip = tmp + tgt_l;
    }
    out_s = malloc(strlen(org_s) + (rep_l - tgt_l) * n + 1);
    if (!out_s) {
        return nullptr;
    }
    tmp = out_s;
    ip = (char *)org_s;
    while (n--) {
        char *p = strstr(ip, tgt_s);
        head_l = p - ip;
        strnz__cpy(tmp, ip, head_l);
        tmp += head_l;
        strnz__cpy(tmp, rep_s, MAXLEN - 1);
        tmp += rep_l;
        ip += head_l + tgt_l;
    }
    strnz__cpy(tmp, ip, MAXLEN - 1);
    return out_s;

References strnz__cpy().

Referenced by exec_objects(), expand_tilde(), and form_exec_receiver().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ssnprintf()

size_t ssnprintf	(	char *	buf,
		size_t	buf_size,
		const char *	format,
			... )

ssnprintf was designed to be a safer alternative to snprintf.

It ensures that the buffer is not overflowed by taking the buffer size as a parameter and using vsnprintf internally. It also returns the number of characters that would have been written if enough space had been available, allowing the caller to detect truncation. This function is particularly useful in situations where the formatted string may exceed the buffer size, as it prevents buffer overflows and provides a way to handle such cases gracefully.

Parameters

buf	- buffer to receive formatted string
buf_size	- size of buffer
format	- printf-style format string
...	- arguments

Returns: number of characters that would have been written if enough space had been available

Definition at line 420 of file futil.c.

                                                                      {
    size_t n;
    va_list args;
 
    va_start(args, format);
    n = vsnprintf(buf, buf_size, format, args);
    va_end(args);
 
    return n;
}

Referenced by action_disposition(), answer_yn(), check_panels(), compile_chyron(), debug_out(), display_error(), display_line(), enter_file_spec(), fork_exec(), form_desc_error(), form_parse_desc(), form_process(), form_write(), get_clr_pair(), get_user_str(), handle_signal(), init_view_boxwin(), init_view_full_screen(), lp(), mapp_initialization(), menu_engine(), mk_dir(), new_init(), new_pick(), new_view(), open_cmenu_log(), open_pick_win(), pad_refresh(), parse_menu_description(), Perror(), picker(), search(), set_chyron_key(), set_chyron_key_cp(), signal_handler(), stdio_fdnames(), stdio_names(), verify_dir(), verify_file(), view_cmd_processor(), view_init_input(), wait_continue(), wait_mk_win(), waitpid_with_timeout(), write_config(), and write_view_buffer().

Here is the caller graph for this function:

◆ str_subc()

bool str_subc	(	char *	d,
		char *	s,
		char	ReplaceChr,
		char *	Withstr,
		int	l )

Replaces "ReplaceChr" in "s" with "Withstr" in "d" won't copy more than "l" bytes to "d" Replaces all occurrences of a character in a string with another string, copying the result to a destination buffer.

Parameters

d	- destination string
s	- source string
ReplaceChr	- character to replace
Withstr	- string to insert
l	- maximum length to copy

Returns: true if successful, false if any parameter is invalid

This function ensures that the total length of the resulting string does not exceed the specified limit, and that the result is null-terminated. This function is useful for simple string substitutions where you want to replace a single character with a longer string, such as replacing spaces with underscores or tabs with spaces.

Note: The caller must ensure that "d" has enough space to receive the result, and that "l" is sufficient to hold the result. This function does not perform any bounds checking on "d" or "Withstr", so it is the caller's responsibility to ensure that they are valid and that "l" is appropriate for the operation.

Definition at line 690 of file futil.c.

                                                                       {
    char *e;
    if (s == nullptr || d == nullptr || Withstr == nullptr || l == 0) {
        if (d != nullptr && l > 0)
            *d = '\0';
        return false;
    }
    e = d + l;
    while (*s != '\0' && d < e) {
        if (*s == ReplaceChr) {
            while (*Withstr != '\0' && d < e)
                *d++ = *Withstr++;
            s++;
        } else
            *d++ = *s++;
    }
    *d = '\0';
    return true;
}

Referenced by view_cmd_processor().

Here is the caller graph for this function:

◆ str_to_args()

int str_to_args	(	char **	argv,
		char *	arg_str,
		int	max_args )

Converts a string into an array of argument strings.

Parameters

argv	- array of pointers to arguments
arg_str	- string containing arguments
max_args	- maximum number of arguments to parse

Returns: argc, a count of allocated vectors in argv

Handles quoted strings and escaped quotes, preserving text inside quotes as individual arguments. It has been in service for many years without problems.

Note: The caller is responsible for deallocating the strings in argv.

Definition at line 440 of file futil.c.

                                                          {
    if (arg_str == nullptr || *arg_str == '\0')
        return 0;
    int argc = 0;
    char *p = arg_str;
    char tmp_str[MAXLEN];
    int in_quotes = 0;
    char *d = tmp_str;
 
    while (*p != '\0' && argc < max_args) {
        while (isspace((unsigned char)*p))
            p++;
        if (*p == '\0')
            break;
        if (*p == '"') {
            in_quotes = 1;
            p++;
        }
        while (*p != '\0') {
            if (in_quotes) {
                if (*p == '\\' && *(p + 1) == '"') {
                    *d++ = '"';
                    p += 2;
                } else if (*p == '"') {
                    *d++ = '\0';
                    p++;
                    in_quotes = 0;
                    break;
                } else
                    *d++ = *p++;
            } else {
                if (isspace((unsigned char)*p)) {
                    *d++ = '\0';
                    p++;
                    break;
                } else
                    *d++ = *p++;
            }
        }
        *d = '\0';
        d = tmp_str;
        argv[argc++] = strdup(tmp_str);
    }
    argv[argc] = nullptr;
    return argc;
}

Referenced by enter_file_spec(), exec_objects(), form_exec_receiver(), form_process(), init_pick(), menu_cmd_processor(), and view_init_input().

Here is the caller graph for this function:

◆ str_to_double()

double str_to_double ( char * s )

converts string to double

Parameters

s	- string to convert

Returns: converted double value, or 0.0 if s is nullptr, empty, or invalid

Note: The caller must ensure that the string is a valid representation of a double before calling this function.

Definition at line 929 of file futil.c.

                              {
    char *e;
    double d;
 
    if (!s || !*s)
        return false;
    d = strtod(s, &e);
    return d;

Referenced by process_config_file().

Here is the caller graph for this function:

◆ str_to_lower()

bool str_to_lower ( char * s )

Converts a string to lowercase.

Parameters

s	- string to convert

Returns: true if successful, false if s is nullptr or empty

Definition at line 508 of file futil.c.

                           {
    if (s == nullptr || *s == '\0')
        return false;
    while (*s != '\0') {
        if (*s >= 'A' && *s <= 'Z')
            *s = *s + 'a' - 'A';
        s++;
    }
    return true;
}

Referenced by clr_name_to_idx(), and form_parse_desc().

Here is the caller graph for this function:

◆ str_to_upper()

bool str_to_upper ( char * s )

Converts a string to uppercase.

Parameters

s	- string to convert

Returns: true if successful, false if s is nullptr or empty

Definition at line 522 of file futil.c.

                           {
    if (s == nullptr || *s == '\0')
        return false;
    while (*s != '\0') {
        if (*s >= 'a' && *s <= 'z')
            *s = *s + 'A' - 'a';
        s++;
    }
    return true;
}

◆ strip_ansi()

size_t strip_ansi	(	char *	d,
		char *	s )

Strips ANSI SGR escape sequences (ending in 'm') from string s to d.

Parameters

d	Destination string
s	Source string

Returns: Length of stripped string
char dest[1024];

char src[] = "\033[31mThis is red text\033[0m

size_t len = strip_ansi(dest, src);

Result: dest = "This is red text", len = 17

@example stripansi.c

Only handles SGR sequences ending in 'm' or 'K' Skips non-ASCII characters The caller must ensure that d has enough space to hold the stripped string This function does not allocate memory; it assumes d is pre-allocated This function processes the entire string until the null terminator This function does not modify the source string s

Definition at line 829 of file futil.c.

                                    {
    size_t l = 0;
    while (*s) {
        if (*s == '\033') {
            while (*s && *s != 'm' && *s != 'K')
                s++;
            if (*s == 'm' || *s == 'K')
                s++;
            continue;
        } else {
            if ((unsigned char)*s <= 127) {
                *d++ = *s++;
                l++;
            } else
                s++;
        }
    }
    *d = '\0';
    return l;

Referenced by main(), and write_view_buffer().

Here is the caller graph for this function:

◆ strip_quotes()

bool strip_quotes ( char * s )

removes leading and trailing double quotes if present

Parameters

s	- string to strip quotes from

Returns: true if successful, false if s is nullptr or empty

If the string has a leading double quote and a trailing double quote, this function removes them in place. If the string does not have both leading and trailing double quotes, it is left unchanged. The function returns true if the operation was successful (i.e., if the string was modified or if it was valid), and false if the input string was null or empty.

Definition at line 718 of file futil.c.

                           {
    if (s == nullptr)
        return false;
    int l = strlen(s);
    if (l > 1 && s[l - 1] == '\"') {
        memmove(s, s + 1, l - 2);
        s[l - 2] = '\0';
    }
    return true;
}

Referenced by init_form_files(), and init_view_files().

Here is the caller graph for this function:

◆ stripz_quotes()

bool stripz_quotes ( char * s )

removes leading and trailing double quotes if present

Parameters

s	- string to strip quotes from

Returns: true if quotes were removed

Same as STRIP_QUOTES but returns true if quotes were removed

Definition at line 733 of file futil.c.

                            {
    if (s == nullptr || strlen(s) < 2)
        return false;
    int l = strlen(s);
    if (l > 1 && s[0] == '\"' && s[l - 1] == '\"') {
        memmove(s, s + 1, l - 2);
        s[l - 2] = '\0';
        return true;
    }
    return false;
}

Referenced by verify_spec_arg().

Here is the caller graph for this function:

◆ strnlf()

size_t strnlf	(	char *	s,
		size_t	max_len )

terminates string with line feed

Parameters

s	string to terminate
max_len	maximum length to scan

Returns: length of resulting string

Definition at line 633 of file futil.c.

                                       {
    char *e;
    size_t len = 0;
    if (s == nullptr || *s == '\0' || max_len == 0)
        return 0;
    e = s + max_len;
    while (*s != '\0' && *s != '\n' && *s != '\r' && s < e) {
        s++;
        len++;
    }
    *s++ = '\n';
    len++;
    *s = '\0';
    return (len);
}

Referenced by write_view_buffer().

Here is the caller graph for this function:

◆ strnz()

size_t strnz	(	char *	s,
		size_t	max_len )

terminates string at New Line, Carriage Return, or max_len

Parameters

s	string to terminate
max_len	- maximum length to scan

Returns: length of resulting string

The use case is to ensure that strings read from files or user input do not contain embedded newlines or carriage returns.

Definition at line 615 of file futil.c.

                                      {
    char *e;
    size_t len = 0;
    if (s == nullptr || *s == '\0' || max_len == 0)
        return 0;
    e = s + max_len;
    while (*s != '\0' && *s != '\n' && *s != '\r' && s < e) {
        s++;
        len++;
    }
    *s = '\0';
    return (len);
}

Referenced by answer_yn(), border_hsplit_text(), display_error(), display_form(), enter_file_spec(), form_display_fields(), form_fmt_field(), message_win(), and Perror().

Here is the caller graph for this function:

◆ strnz__cat()

size_t strnz__cat	(	char *	d,
		const char *	s,
		size_t	max_len )

safer alternative to strncat

Parameters

d	- destination string
s	- source string
max_len	- maximum length to copy

Returns: length of resulting string

Append string s to d, ensuring that the total length of d does not exceed max_len, and that the resulting string is null-terminated. It also treats newline and carriage return characters as string terminators, preventing them from being included in the result. This is particularly useful when concatenating user input or file data, where embedded newlines could cause issues.

Definition at line 573 of file futil.c.

                                                          {
    char *e;
    size_t len = 0;
    if (s == nullptr || d == nullptr || max_len == 0) {
        if (d != nullptr && max_len > 0)
            *d = '\0';
        return 0;
    }
    e = d + max_len;
    while (*d != '\0' && *d != '\n' && *d != '\r' && d < e) {
        d++;
        len++;
    }
    while (*s != '\0' && *s != '\n' && *s != '\r' && d < e) {
        *d++ = *s++;
        len++;
    }
    *d = '\0';
    return len;
}

Referenced by build_prompt(), derive_file_spec(), display_form(), display_pick_help(), enter_file_spec(), exec_objects(), expand_tilde(), file_spec_parts(), form_engine(), form_exec_cmd(), form_exec_receiver(), form_parse_desc(), form_process(), form_read_data(), form_write(), get_ip_addresses(), init_form(), init_menu_files(), init_pick(), init_view_files(), locate_file_in_path(), mapp_initialization(), menu_cmd_processor(), mk_dir(), new_pick_view(), new_view_file(), open_curses(), output_objects(), parse_menu_description(), picker(), popup_ckeys(), search(), stdio_fdnames(), stdio_names(), verify_spec_arg(), view_cmd_processor(), view_display_help(), view_init_input(), whence(), write_cmenu_log(), write_config(), and write_view_buffer().

Here is the caller graph for this function:

◆ strnz__cpy()

size_t strnz__cpy	(	char *	d,
		const char *	s,
		size_t	max_len )

safer alternative to strncpy

copies string s to d, ensuring that the total length of d does not exceed max_len, and that the resulting string is null-terminated. It also treats newline and carriage return characters as string terminators, preventing them from being included in the result. This is particularly useful when copying user input or file data, where embedded newlines could cause issues.

Parameters

d	- destination string
s	- source string
max_len	- maximum length to copy

Returns: length of resulting string

Definition at line 544 of file futil.c.

                                                          {
    char *e;
    size_t len = 0;
    if (s == nullptr || d == nullptr || max_len == 0) {
        if (d != nullptr && max_len > 0)
            *d = '\0';
        return 0;
    }
    e = d + max_len;
    while (*s != '\0' && *s != '\n' && *s != '\r' && d < e) {
        *d++ = *s++;
        len++;
    }
    *d = '\0';
    return len;
}

Referenced by answer_yn(), build_prompt(), canonicalize_file_spec(), derive_file_spec(), dir_name(), display_error(), display_form(), display_pick_help(), display_prompt(), enter_file_spec(), exec_objects(), expand_tilde(), file_spec_parts(), form_desc_error(), form_engine(), form_exec_cmd(), form_exec_receiver(), form_fmt_field(), form_parse_desc(), form_process(), form_read_data(), form_write(), get_argp_doc_by_name(), get_cmd_arg(), handle_signal(), init_form(), init_form_files(), init_menu_files(), init_pick(), init_pick_files(), init_view_files(), locate_file_in_path(), main(), mapp_initialization(), menu_cmd_processor(), mk_dir(), new_form(), new_pick_view(), new_view_file(), open_cmenu_log(), open_curses(), output_objects(), parse_menu_description(), Perror(), picker(), popup_ckeys(), process_config_file(), process_config_files(), rep_substring(), save_object(), search(), stdio_fdnames(), stdio_names(), verify_dir(), verify_file(), verify_spec_arg(), view_cmd_processor(), view_display_help(), view_file(), view_init_input(), whence(), write_cmenu_log(), write_config(), and write_view_buffer().

Here is the caller graph for this function:

◆ strnz_dup()

char * strnz_dup	(	char *	s,
		size_t	l )

Allocates memory for and duplicates string s up to length l or until line feed or carriage return.

Parameters

s	- string to duplicate
l	- maximum length to copy

Returns: pointer to allocated memory

Definition at line 654 of file futil.c.

                                   {
    char *p, *ms, *e;
    size_t m;
    if (s == nullptr || *s == '\0' || l == 0)
        return nullptr;
    for (p = s, m = 1; *p != '\0'; p++, m++)
        ;
    ms = p = (char *)malloc(m);
    if (ms != nullptr) {
        e = ms + l;
        while (*s != '\0' && *s != '\n' && *s != '\r' && p < e)
            *p++ = *s++;
        *p = '\0';
    }
    return ms;
}

Referenced by new_view().

Here is the caller graph for this function:

◆ strz()

size_t strz ( char * s )

Terminates string at new line or carriage return.

Parameters

s	string to terminate

Definition at line 597 of file futil.c.

                     {
    size_t l = 0;
    if (s == nullptr || *s == '\0')
        return 0;
    while (*s != '\0' && *s != '\n' && *s != '\r') {
        s++;
        l++;
    }
    *s = '\0';
    return l;
}

◆ trim()

size_t trim ( char * s )

Trims leading and trailing spaces from string s in place.

Parameters

s	- string to trim

Returns: length of trimmed string

Definition at line 391 of file futil.c.

                     {
    if (s == nullptr || *s == '\0')
        return 0;
    char *p = s;
    char *d = s;
    while (*p == ' ')
        p++;
    while (*p != '\0')
        *d++ = *p++;
    while (*(d - 1) == ' ' && d > s)
        d--;
    *d = '\0';
    return (size_t)(d - s);
}

Referenced by form_fmt_field(), form_parse_desc(), left_justify(), menu_cmd_processor(), parse_menu_description(), and right_justify().

Here is the caller graph for this function:

◆ trim_ext()

bool trim_ext	(	char *	buf,
		char *	filename )

trims the file extension from "filename" and copies the result to "buf"

Parameters

buf	- buffer to receive result
filename	- filename to trim

Note: The caller is responsible for ensuring that "buf" has enough space to receive the result.

Definition at line 1016 of file futil.c.

                                         {
    if (!filename || !*filename || !buf)
        return false;
    char *s = filename;
    char *d = buf;
    *d = '\0';
    while (*s)
        s++;
    while (filename < --s) {
        if (*s == '.') {
            break;
        }
    }
    if (*s != '.') {
        while (*filename)
            *d++ = *filename++;
    } else {
        while (filename < s) {
            *d++ = *filename++;
        }
    }
    *d = '\0';
    if (d == buf)
        return false;
    return true;

◆ trim_path()

bool trim_path ( char * dir )

Trims trailing spaces and slashes from directory path in place.

Parameters

dir	- directory path to trim

Returns: true if successful

Definition at line 988 of file futil.c.

                          {
    if (!dir)
        return false;
    char *p;
 
    if (!dir || !*dir)
        return false;
    p = dir;
    while (*p++ != '\0') {
        if (*p == ' ' || *p == '\t' || *p == '\n') {
            *p = '\0';
            break;
        }
    }
    --p;
    while (--p > dir && *p == '/') {
        if (*(p - 1) != '~')
            *p = '\0';
    }
    return true;

Referenced by derive_file_spec().

Here is the caller graph for this function:

◆ ui_rect_set()

void ui_rect_set	(	UiRect *	r,
		int	y,
		int	x,
		int	h,
		int	w )

Set the properties of a UiRect structure.

ui_rect_set

Parameters

r	Pointer to the UiRect structure to set
y	Y-coordinate (row) of the rectangle's top-left corner
x	X-coordinate (column) of the rectangle's top-left corner
h	Height (number of rows) of the rectangle
w	Width (number of columns) of the rectangle

This function initializes the fields of a UiRect structure with the specified values for position and size. It is used to define rectangular areas in a user interface.

Definition at line 908 of file dwin.c.

                                                        {
    r->y = y;
    r->x = x;
    r->rows = h;
    r->cols = w;
}

References UiRect::cols, UiRect::rows, UiRect::x, and UiRect::y.

◆ unstr_hex_clr()

bool unstr_hex_clr	(	char *	dst,
		char *	str )

Validates that a string is a hex color code in the format "#RRGGBB".

Parameters

dst	- buffer to receive validated hex color string
str	- input string to validate

Returns: true if str is a valid hex color code, false otherwise

This function checks that the input string starts with a '#' character, followed by exactly six hexadecimal digits (0-9, A-F, a-f). If the input string is valid, it copies the hex color code into the provided destination buffer. The caller must ensure that dst has enough space to hold the resulting string (at least 8 characters including the null terminator). If the input string is invalid (e.g., does not start with '#', contains non-hex characters, or does not have exactly six hex digits), this function returns false and does not modify the destination buffer.

Definition at line 232 of file futil.c.

                                         {
    char *s = str;
    char *e;
    char *d;
    if (s == NULL || *s == '\0')
        return false;
    if (*s != '#')
        return false;
    d = dst;
    *d++ = *s++;
    e = (s + 6);
    while (s < e && *s != '\0') {
        if (!isxdigit(*s)) {
            return false;
        }
        *d++ = *s++;
    }
    *d = '\0';
    if ((int)(s - str) != 7)
        return false;
    return true;
}

Referenced by process_config_file().

Here is the caller graph for this function:

◆ verify_dir()

bool verify_dir	(	char *	spec,
		int	imode )

Verifies that the directory specified by "spec" exists and is accessible with the permissions specified by "imode".

Parameters

spec	- directory specification
imode	- access mode F_OK - existence R_OK - read W_OK - Write X_OK - Execute S_WCOK - Write or Create S_QUIET - Suppress Error Messages

Returns: true if successful

S_WCOK and S_QUIET are stripped before calling faccessat

Definition at line 1189 of file futil.c.

                                       {
    if (spec == nullptr || *spec == '\0')
        return false;
    expand_tilde(spec, MAXLEN);
    struct stat sb;
    errno = 0;
    src_line = 0;
    int mode = imode & ~(S_WCOK | S_QUIET);
    if (faccessat(AT_FDCWD, spec, mode, AT_EACCESS) != 0) {
        src_line = __LINE__ - 2;
        src_name = __FILE__;
        strnz__cpy(fn, "faccessat", MAXLEN - 1);
    } else {
        if (fstatat(AT_FDCWD, spec, &sb, 0) != 0) {
            src_line = __LINE__ - 1;
            src_name = __FILE__;
            strnz__cpy(fn, "fstatat", MAXLEN - 1);
        } else {
            if ((sb.st_mode & S_IFMT) != S_IFDIR) {
                src_line = __LINE__ - 1;
                src_name = __FILE__;
                strnz__cpy(fn, "verify_file", MAXLEN - 1);
                strnz__cpy(em2, "Not a regular file.", MAXLEN - 1);
            }
        }
    }
    if (src_line != 0) {
        if (!(mode & S_QUIET)) {
            ssnprintf(em0, MAXLEN - 1, "%s failed in %s at line %d", fn,
                      src_name, src_line);
            strnz__cpy(em1, spec, MAXLEN - 1);
            strnz__cpy(em3, "Check the file", MAXLEN - 1);
            display_error(em0, em1, em2, em3);
        }
        return false;
    }
    return true;

References display_error(), em0, em1, em2, em3, expand_tilde(), fn, src_line, src_name, ssnprintf(), and strnz__cpy().

Referenced by mapp_initialization(), mk_dir(), and verify_spec_arg().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verify_file()

bool verify_file	(	char *	in_spec,
		int	imode )

Verifies that the file specified by "in_spec" exists and is accessible with the permissions specified by "imode".

Parameters

in_spec	- directory specification
imode	- access mode F_OK - existence R_OK - read W_OK - Write X_OK - Execute S_WCOK - Write or Create S_QUIET - Suppress Error Messages

Returns: true if successful

S_WCOK and S_QUIET are stripped before calling faccessat

Definition at line 1240 of file futil.c.

                                           {
    if (in_spec == nullptr || *in_spec == '\0')
        return false;
    struct stat sb;
    char spec[MAXLEN];
    strnz__cpy(spec, in_spec, MAXLEN - 1);
    int mode = imode & ~(S_WCOK | S_QUIET);
    errno = 0;
    src_line = 0;
    canonicalize_file_spec(spec);
    expand_tilde(spec, MAXLEN);
    if ((faccessat(AT_FDCWD, spec, mode, AT_EACCESS)) != 0) {
        src_line = __LINE__ - 1;
        src_name = __FILE__;
        strnz__cpy(fn, "faccessat", MAXLEN - 1);
    } else {
        if ((fstatat(AT_FDCWD, spec, &sb, 0)) != 0) {
            src_line = __LINE__ - 1;
            src_name = __FILE__;
            strnz__cpy(fn, "fstatat", MAXLEN - 1);
        } else {
            if ((sb.st_mode & S_IFMT) != S_IFREG) {
                src_line = __LINE__ - 1;
                src_name = __FILE__;
                strnz__cpy(fn, "verify_file", MAXLEN - 1);
                strnz__cpy(em2, "Not a regular file.", MAXLEN - 1);
            }
        }
    }
    if (src_line != 0) {
        if (imode & S_QUIET)
            return false;
        ssnprintf(em0, MAXLEN - 1, "%s failed in %s at line %d", fn, src_name,
                  src_line);
        strnz__cpy(em1, spec, MAXLEN - 1);
        strnz__cpy(em3, "Check the file", MAXLEN - 1);
        display_error(em0, em1, em2, em3);
        return false;
    }
    return true;

References canonicalize_file_spec(), display_error(), em0, em1, em2, em3, expand_tilde(), fn, src_line, src_name, ssnprintf(), and strnz__cpy().

Referenced by verify_spec_arg().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wccp_to_str()

int wccp_to_str	(	wchar_t	cp,
		uint8_t *	buffer )

Converts a Unicode code point to a UTF-8 encoded string.

Parameters

cp	- Unicode code point to convert
buffer	- buffer to receive UTF-8 encoded string (must be at least 4 bytes)

Returns: number of bytes written to buffer, or 0 if cp is invalid

This function encodes the given Unicode code point into its UTF-8 representation and stores it in the provided buffer. The caller must ensure that the buffer has enough space to hold the resulting UTF-8 string (up to 4 bytes for code points up to U+10FFFF). If the code point is invalid (e.g., greater than U+10FFFF), this function returns 0 and does not modify the buffer.

Definition at line 871 of file dwin.c.

                                             {
    if (cp <= 0x7F) {
        // 1-byte sequence: 0xxxxxxx
        buffer[0] = (uint8_t)cp;
        return 1;
    } else if (cp <= 0x7FF) {
        // 2-byte sequence: 110xxxxx 10xxxxxx
        buffer[0] = (uint8_t)(0xC0 | ((cp >> 6) & 0x1F));
        buffer[1] = (uint8_t)(0x80 | (cp & 0x3F));
        return 2;
    } else if (cp <= 0xFFFF) {
        // 3-byte sequence: 1110xxxx 10xxxxxx 10xxxxxx
        buffer[0] = (uint8_t)(0xE0 | ((cp >> 12) & 0x0F));
        buffer[1] = (uint8_t)(0x80 | ((cp >> 6) & 0x3F));
        buffer[2] = (uint8_t)(0x80 | (cp & 0x3F));
        return 3;
    } else if (cp <= 0x10FFFF) {
        // 4-byte sequence: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
        buffer[0] = (uint8_t)(0xF0 | ((cp >> 18) & 0x07));
        buffer[1] = (uint8_t)(0x80 | ((cp >> 12) & 0x3F));
        buffer[2] = (uint8_t)(0x80 | ((cp >> 6) & 0x3F));
        buffer[3] = (uint8_t)(0x80 | (cp & 0x3F));
        return 4;
    }
    return 0; // Invalid Unicode code point
}

◆ write_cmenu_log()

void write_cmenu_log ( char * msg )

Write message to C-Menu log file with timestamp.

Parameters

msg	- string to write to log file

Definition at line 1685 of file futil.c.

                                {
    char time_buf[100];
    time_t now = time(NULL);
    struct tm *t = localtime(&now);
    strftime(time_buf, sizeof(time_buf), "%Y-%m-%dT%H:%M:%S%z", t);
    strnz__cpy(em1, time_buf, MAXLEN - 1);
    strnz__cat(em1, " ", MAXLEN - 1);
    strnz__cat(em1, msg, MAXLEN - 1);
    write(cmenu_log_fd, em1, strlen(em1));
    write(cmenu_log_fd, "\n", 1);
    return;

References cmenu_log_fd, em1, strnz__cat(), and strnz__cpy().

Referenced by open_cmenu_log().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write_cmenu_log_nt()

void write_cmenu_log_nt ( char * msg )

Write message to C-Menu log file without timestamp.

Parameters

msg	- string to write to log file

Definition at line 1701 of file futil.c.

                                   {
    write(cmenu_log_fd, msg, strlen(msg));
    write(cmenu_log_fd, "\n", 1);
    return;

References cmenu_log_fd.

Functions

Detailed Description

Function Documentation

◆ a_to_ul()

◆ a_toi()

◆ base_name()

◆ canonicalize_file_spec()

◆ chrep()

◆ destroy_argv()

◆ dir_name()

◆ expand_tilde()

◆ fdname()

◆ file_spec_name()

◆ file_spec_path()

◆ format_local_timestamp()

◆ get_argp_doc_by_name()

◆ get_ip_addresses()

◆ get_local_timestamp()

◆ get_user_str()

◆ is_directory()

◆ is_hex_str()

◆ is_newer()

◆ is_symlink_to_dir()

◆ is_valid_regex()

◆ iso8601_time()

◆ locate_file_in_path()

◆ mk_dir()

◆ normalize_file_spec()

◆ open_cmenu_log()

◆ parse_local_timestamp()

◆ rep_substring()

◆ ssnprintf()

◆ str_subc()

◆ str_to_args()

◆ str_to_double()

◆ str_to_lower()

◆ str_to_upper()

◆ strip_ansi()

◆ strip_quotes()

◆ stripz_quotes()

◆ strnlf()

◆ strnz()

◆ strnz__cat()

◆ strnz__cpy()

◆ strnz_dup()

◆ strz()

◆ trim()

◆ trim_ext()

◆ trim_path()

◆ ui_rect_set()

◆ unstr_hex_clr()

◆ verify_dir()

◆ verify_file()

◆ wccp_to_str()

◆ write_cmenu_log()

◆ write_cmenu_log_nt()