Base File Library¶

Overview¶

The file library in Cozenage provides a comprehensive interface for interacting with the filesystem, bridging the gap between high-level Scheme logic and low-level system calls. It offers a robust set of predicates to identify file types—ranging from regular files and directories to specialized Unix entities like symbolic links, sockets, and FIFOs. By leveraging these tools, developers can write portable and defensive code that verifies the nature of a path before attempting operations, ensuring that the interpreter handles external data gracefully.

Beyond simple identification, the library supports essential filesystem manipulations such as creating and removing directories or unlinking files. It also exposes detailed metadata through a powerful stat interface, providing access to file sizes, ownership, and high-precision timestamps (atime, mtime, and ctime) in both machine-readable and human-readable formats. Whether you are building a build-system tool, a simple file navigator, or a data-logging application, this library provides the necessary primitives to manage the environment surrounding your Cozenage programs.

File, Device, and Pipe Predicates¶

reg-file?¶

(reg-file? path)

Returns #true if the file at path exists and is a regular file.

Parameters:: path (string) – The path to the file.
Returns:: #true or #false.
Return type:: boolean

Example

--> (reg-file? "/etc/passwd")
  #true
--> (reg-file? "/bin")
  #false

directory?¶

(directory? path)

Returns #true if the file at path exists and is a directory.

Parameters:: path (string) – The path to the directory.
Returns:: #true or #false.
Return type:: boolean

Example

--> (directory? "/tmp")
#true

symlink?¶

(symlink? path)

Returns #true if the file at path exists and is a symbolic link.

Parameters:: path (string) – The path to the file.
Returns:: #true or #false.
Return type:: boolean

char-device?¶

(char-device? path)

Returns #true if the file at path exists and is a character device.

Parameters:: path (string) – The path to the file.
Returns:: #true or #false.
Return type:: boolean

block-device?¶

(block-device? path)

Returns #true if the file at path exists and is a block device.

Parameters:: path (string) – The path to the file.
Returns:: #true or #false.
Return type:: boolean

fifo?¶

(fifo? path)

Returns #true if the file at path exists and is a FIFO (named pipe).

Parameters:: path (string) – The path to the file.
Returns:: #true or #false.
Return type:: boolean

socket?¶

(socket? path)

Returns #true if the file at path exists and is a Unix domain socket.

Parameters:: path (string) – The path to the file.
Returns:: #true or #false.
Return type:: boolean

file-exists?¶

(file-exists? path)

Returns #true if a file or directory exists at path.

Parameters:: path (string) – The path to check.
Returns:: #true or #false.
Return type:: boolean

Basic File Operations¶

mkdir¶

(mkdir path)

Creates the directory named by path. If path is relative, it is created in the current working directory. Default permissions are 0755.

Parameters:: path (string) – The name of the directory to create.
Returns:: #true on success.
Return type:: boolean

rmdir!¶

(rmdir! path)

Removes the directory pointed to by path. The directory must be empty.

Parameters:: path (string) – The path to the directory to remove.
Returns:: #true on success.
Return type:: boolean

unlink!¶

(unlink! path)

Unlinks (and possibly deletes) the file pointed to by path.

Parameters:: path (string) – The path to the file.
Returns:: #true on success.
Return type:: boolean

File Metadata and Permissions¶

stat¶

(stat path)

Returns an association list containing the status information for the file at path.

Parameters:: path (string) – The path to the file.
Returns:: An alist of file attributes (e.g., size, mode, uid, gid).
Return type:: list

Example

--> (stat "README.md")
  ((type . "regular") (st_size . 1240) (st_mode . "-rw-r--r--") ...)

file-size¶

(file-size path)

Returns the size in bytes of the file pointed to by path.

Parameters:: path (string) – The path to the file.
Returns:: The size in bytes.
Return type:: integer

Extended Timestamp Procedures¶

file-mtime¶

(file-mtime path)

Returns a list representing the last modified time of the file.

Parameters:: path (string) – The path to the file.
Returns:: A list containing (seconds nanoseconds human-readable-string).
Return type:: list

Example

--> (file-mtime "main.c")
  (1706728331 387617529 "2026-01-31 19:12:11.387617529 PST")

file-atime¶

(file-atime path)

Returns a list representing the last access time (atime) of the file pointed to by path.

Parameters:: path (string) – The path to the file.
Returns:: A list containing (seconds nanoseconds human-readable-string).
Return type:: list

file-ctime¶

(file-ctime path)

Returns a list representing the last status change time (ctime) of the file pointed to by path. Note that on Unix systems, this typically refers to metadata changes (like permissions) rather than file creation.

Parameters:: path (string) – The path to the file.
Returns:: A list containing (seconds nanoseconds human-readable-string).
Return type:: list

Permission Predicates¶

file-readable?¶

(file-readable? path)

Returns #true if the currently running process has read permissions for the file or directory.

Parameters:: path (string) – The path to check.
Returns:: #true or #false.
Return type:: boolean

file-writable?¶

(file-writable? path)

Returns #true if the currently running process has write permissions for the file or directory pointed to by path.

Parameters:: path (string) – The path to check.
Returns:: #true or #false.
Return type:: boolean

Example

--> (file-writable? "/etc/shadow")
#false
--> (file-writable? "/tmp/my-temp-file")
#true

file-executable?¶

(file-executable? path)

Returns #true if the currently running process has execute permissions for the file or directory pointed to by path. For directories, “execute” permission allows the process to enter or search the directory.

Parameters:: path (string) – The path to check.
Returns:: #true or #false.
Return type:: boolean