zpmod_fs.h File Reference

Filesystem helpers used by builtins and zpmod subcommands. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
int	zp_pathstat_core (char *nam, char *outname, char *inname, int follow, char *fields)
	Batch stat entries from an input array into an output array. More...
int	zp_dirlist_core (char *nam, char *outname, char *dir, int inc_all, int only_dirs, int only_files)
	List directory entries into an output array with filters. More...
int	zp_readfile_core (char *nam, char *outname, char *path, int use_mmap, int split, int delim)
	Read a file into a scalar or split into an array by delimiter. More...
int	zp_path_warmup_core (const char *nam, int quiet, int prune_missing, int dry_run)
	Scan $PATH directories to warm filesystem caches and prepare command lookup. More...

Detailed Description

Filesystem helpers used by builtins and zpmod subcommands.

These functions perform the core work for filesystem-related builtins. They follow zsh module conventions:

• All string allocations use zsh allocators (zalloc/zsfree/zfree).
• When a function returns a newly allocated buffer and also provides the buffer length, call sites must free with the exact length.
• Parameters named nam are the reporting name (builtin/subcommand) used with zsh’s zwarn/zerr helpers.

Definition in file zpmod_fs.h.

Function Documentation

zp_dirlist_core()

int zp_dirlist_core	(	char *	nam,
		char *	outname,
		char *	dir,
		int	inc_all,
		int	only_dirs,
		int	only_files
	)

List directory entries into an output array with filters.

Parameters

nam	Reporting name for diagnostics.
outname	Name of the output indexed array parameter to populate.
dir	Directory to scan (metafied string).
inc_all	Include dotfiles when non-zero.
only_dirs	Include only directories when non-zero.
only_files	Include only regular files when non-zero.

Returns

0 on success; non-zero on error.

List directory entries into an output array with filters.

Definition at line 382 of file fs.c.

References metafy(), PATH_MAX, setaparam(), setsparam(), unsetparam(), zalloc(), zfree(), zp_unmetafy_zalloc(), and zwarnnam().

Referenced by bin_zpdirlist(), and cmd_dirlist().

Here is the call graph for this function:

Here is the caller graph for this function:

zp_path_warmup_core()

int zp_path_warmup_core	(	const char *	nam,
		int	quiet,
		int	prune_missing,
		int	dry_run
	)

Scan $PATH directories to warm filesystem caches and prepare command lookup.

Prototype implementation: walks each entry in the shell's $path, opens the directory and stats executable entries. This warms kernel VFS caches and can reduce the cost of a subsequent rehash.

Parameters

nam	Reporting name for diagnostics.
quiet	Suppress progress output when non-zero.
prune_missing	Reserved for future integration (currently no-op).

Returns

number of executables observed (>=0) on success; negative on error.

Scan $PATH directories to warm filesystem caches and prepare command lookup.

This function provides two main features:

1. Executable Discovery: Scans all directories in $PATH and touches executable files to warm filesystem caches and improve command lookup performance.
2. Path Pruning: Safely removes non-existent directories from $PATH to reduce lookup overhead and eliminate stale entries.

Memory Safety Design

The prune functionality was redesigned to avoid memory corruption issues that occurred when mixing getaparam("path") results with setaparam("path") calls. The original implementation caused double-free errors due to zsh's parameter management internals.

Solution: Use a two-pass approach with separate array construction:

• Pass 1: Count valid directories without modifying the original array
• Pass 2: Build a new array using ztrdup() for proper string ownership
• Safe update: Use setaparam("path", new_array) without dependency on getaparam() result

Parameters

nam	Builtin name for error reporting
quiet	Suppress progress messages if true
prune_missing	Remove non-existent directories from path if true
dry_run	Report what would be pruned without making changes if true

Returns

Number of executable files discovered, or negative on error

Note

This function follows zpmod's memory management patterns using zsh allocators (zalloc, ztrdup, zfree) to ensure compatibility with zsh's garbage collection.

Definition at line 254 of file fs.c.

zp_pathstat_core()

int zp_pathstat_core	(	char *	nam,
		char *	outname,
		char *	inname,
		int	follow,
		char *	fields
	)

Batch stat entries from an input array into an output array.

For each path in inname, writes a metafied key=value record into outname. The set of fields can be filtered via fields.

Parameters

nam	Reporting name for diagnostics (e.g., builtin name).
outname	Name of the output indexed array parameter to populate.
inname	Name of the input indexed array parameter to read.
follow	When non-zero, follow symlinks (stat); otherwise lstat.
fields	Optional comma-separated field filter (e.g., "type,size").

Returns

0 on success; non-zero on error (zwarn already emitted).

Batch stat entries from an input array into an output array.

Definition at line 36 of file fs.c.

References getaparam(), metafy(), setaparam(), setsparam(), unsetparam(), zalloc(), zfree(), zp_unmetafy_zalloc(), and zwarnnam().

Referenced by bin_zppathstat(), and cmd_pathstat().

Here is the call graph for this function:

Here is the caller graph for this function:

zp_readfile_core()

int zp_readfile_core	(	char *	nam,
		char *	outname,
		char *	path,
		int	use_mmap,
		int	split,
		int	delim
	)

Read a file into a scalar or split into an array by delimiter.

Parameters

nam	Reporting name for diagnostics.
outname	Output parameter name: scalar (no split) or array (split).
path	Path of file to read (metafied string).
use_mmap	Hint to use mmap when available and beneficial.
split	When non-zero, split on delimiter into an array.
delim	Delimiter character when splitting (e.g., ' ').

Returns

0 on success; non-zero on error.

Read a file into a scalar or split into an array by delimiter.

Definition at line 444 of file fs.c.

References metafy(), path, setaparam(), setsparam(), unsetparam(), zalloc(), zfree(), zp_unmetafy_zalloc(), zrealloc(), and zwarnnam().

Referenced by bin_zpreadfile(), and cmd_readfile().

Here is the call graph for this function:

Here is the caller graph for this function: