Utility functions

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 (uint 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, uint 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, uint 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, uint 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.
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
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, uint 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, uint 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.
char *	strerror__r (int errnum, char *buf, size_t buflen)
	A thread-safe alternative to strerror() that writes the error message corresponding to errnum into the provided buffer.
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.
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, uint imode)
	Verifies that the directory specified by "spec" exists and is accessible with the permissions specified by "imode".
bool	verify_file (char *in_spec, uint imode)
	Verifies that the file specified by "in_spec" exists and is accessible with the permissions specified by "imode".

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 812 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 784 of file futil.c.

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

Referenced by parse_ansi_str(), ui_assign_chyron_win(), and ui_parse_ansi().

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 1132 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 1350 of file futil.c.

                                          {
    if (spec == nullptr || *spec == '\0')
        return 0;
    char tmp_s[MAXLEN];
    char *s;
    s = spec;
    char *d;
    d = tmp_s;
    uint 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 765 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	(	uint	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 468 of file futil.c.

                                         {
    for (uint 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 1158 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,
		uint	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 989 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 1073 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 916 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 889 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 273 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 164 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,
		uint	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 324 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 284 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 297 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, (uint)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 1381 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,
		uint	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 197 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 ((uint)(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 148 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 1394 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 1409 of file futil.c.

                                         {
    regex_t regex;
    uint 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:

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 1296 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 1329 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);
            ui_display_error(em0, em1, em2, nullptr);
            return false;
        }
        return true;
    }
    return true;

References em0, em1, em2, expand_tilde(), ssnprintf(), strerror__r(), strnz__cat(), strnz__cpy(), ui_display_error(), 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 872 of file futil.c.

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

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 250 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 1449 of file futil.c.

                                                                             {
    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;
    uint tgt_l = strlen(tgt_s);
    uint rep_l = strlen(rep_s);
    uint head_l;
    uint 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;

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 390 of file futil.c.

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

Referenced by debug_out(), display_line(), display_split_line(), enter_file_spec(), finder(), fork_exec(), form_desc_error(), form_parse_desc(), form_process(), form_write(), get_cmd_char(), get_user_str(), handle_signal(), init_view_full_screen(), lp(), mapp_initialization(), menu_engine(), mk_dir(), new_init(), new_pick(), new_view(), open_pick_win(), pad_refresh(), parse_menu_description(), picker(), signal_handler(), stdio_fdnames(), stdio_names(), ui_action_disposition(), ui_add_pair(), ui_answer_yn(), ui_color_from_rgb(), ui_compile_chyron(), ui_display_error(), ui_open_log(), ui_perror(), ui_register_read_fd(), ui_set_chyron_key(), ui_set_chyron_key_cb(), ui_surface_box(), ui_surface_new(), ui_timeout_prompt(), ui_update_timeout_prompt(), verify_dir(), verify_file(), view_cmd_processor(), view_init_input(), 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,
		uint	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 680 of file futil.c.

                                                                        {
    if (d == nullptr || s == nullptr || Withstr == nullptr || l == 0)
        return false;
    char *e;
    if (l == 0) {
        if (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,
		uint	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 412 of file futil.c.

                                                           {
    if (argv == nullptr || arg_str == nullptr || max_args == 0)
        return 0;
    if (*arg_str == '\0')
        return 0;
    uint argc = 0;
    char *p = arg_str;
    char tmp_str[MAXLEN];
    uint 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.

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 948 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 482 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 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 496 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 process_config_file().

Here is the caller graph for this function:

strerror__r()

char * strerror__r	(	int	errnum,
		char *	buf,
		size_t	buflen )

A thread-safe alternative to strerror() that writes the error message corresponding to errnum into the provided buffer.

Parameters

errnum	- error number (typically from errno)
buf	- buffer to receive the error message
buflen	- size of the buffer

Returns

pointer to buf containing the error message, or nullptr if buf is null or buflen is zero

This function uses strerror_r to retrieve the error message in a thread-safe manner. If the error number is unknown, it formats a default message indicating that the error is unknown. The caller must ensure that buf has enough space to hold the resulting string.

Definition at line 748 of file futil.c.

                                                        {
    char tmp_str[MAXLEN];
    if (buf == nullptr || buflen == 0)
        return nullptr;
    strnz__cpy(tmp_str, strerror_r(errnum, buf, buflen), MAXLEN - 1);
    if (buf == nullptr)
        snprintf(buf, buflen, "error %d: unknown error", errnum);
    else
        snprintf(buf, buflen, "error %d: %s", errnum, tmp_str);
    return buf;
}

References strnz__cpy().

Referenced by enter_file_spec(), form_parse_desc(), form_process(), form_write(), mk_dir(), view_cmd_processor(), view_init_input(), and write_view_buffer().

Here is the call graph for this function:

Here is the caller graph for this function:

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 848 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 710 of file futil.c.

                           {
    uint 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 723 of file futil.c.

                            {
    if (s == nullptr || *s == '\0')
        return false;
    if (strlen(s) < 2)
        return false;
    uint 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 619 of file futil.c.

                                       {
    if (s == nullptr || *s == '\0' || max_len == 0)
        return 0;
    char *e;
    size_t len = 0;
    if (*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. WARNING: This function is prone to segmentation faults because it attempts to write a terminating zero. Do not use strnz() on: read-only function arguments such as const and quoted literals or strings not terminated in the first max_len characters

Definition at line 599 of file futil.c.

                                      {
    if (s == nullptr || *s == '\0' || max_len == 0)
        return 0;
    char *e;
    size_t len = 0;
    if (*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 display_form(), enter_file_spec(), form_display_fields(), form_fmt_field(), and ui_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 549 of file futil.c.

                                                          {
    if (d == nullptr || s == nullptr)
        return 0;
    char *e;
    size_t len = 0;
    if (max_len == 0) {
        if (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(), 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_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 518 of file futil.c.

                                                          {
    if (d == nullptr || s == nullptr)
        return 0;
    char *e;
    size_t len = 0;
    if (max_len == 0) {
        if (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 build_prompt(), canonicalize_file_spec(), derive_file_spec(), dir_name(), 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_lf(), init_menu_files(), init_pick(), init_pick_files(), init_view_files(), locate_file_in_path(), log_strnz(), main(), mapp_initialization(), menu_cmd_processor(), mk_dir(), new_form(), new_pick_view(), new_view_file(), output_objects(), parse_menu_description(), picker(), popup_ckeys(), process_config_file(), process_config_files(), rep_substring(), save_object(), search(), stdio_fdnames(), stdio_names(), strerror__r(), ui_answer_yn(), ui_border_ysplit_text(), ui_display_error(), ui_open_log(), ui_perror(), ui_surface_box(), ui_timeout_prompt(), verify_dir(), verify_file(), verify_spec_arg(), view_cmd_processor(), view_display_help(), view_file(), view_init_input(), whence(), 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 642 of file futil.c.

                                   {
    if (s == nullptr || *s == '\0' || l == 0)
        return nullptr;
    char *p, *ms, *e;
    size_t m;
    if (*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 575 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 361 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(), right_justify(), 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 1035 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 1007 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:

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 220 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 ((uint)(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,
		uint	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 1198 of file futil.c.

                                        {
    if (spec == nullptr || *spec == '\0')
        return false;
    expand_tilde(spec, MAXLEN);
    struct stat sb;
    errno = 0;
    src_line = 0;
    uint mode = imode & ~(S_WCOK | S_QUIET);
    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_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);
            ui_display_error(em0, em1, em2, em3);
        }
        return false;
    }
    return true;

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

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,
		uint	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 1249 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);
    uint 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);
        ui_display_error(em0, em1, em2, em3);
        return false;
    }
    return true;

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

Referenced by verify_spec_arg().

Here is the call graph for this function:

Here is the caller graph for this function: