High-level API used by the BSFS browser shell. More...

Functions
int	open_bsfs (FILE disk, superblock_t sb, const char path, file_t file)
	Open a file by path and load its inode into a file_t.
int	close_bsfs (file_t *file)
	Close an open file descriptor (no-op in this API).
int	seek_bsfs (file_t *file, uint32_t pos)
	Set the current file position (absolute) within the open file.
size_t	read_bsfs (FILE disk, superblock_t sb, file_t file, void data, uint32_t length)
	Read up to `length` bytes from the current file position.
size_t	write_bsfs (FILE disk, superblock_t sb, file_t file, void data, uint32_t length)
	Write `length` bytes from `data` at the current file position.
size_t	overwrite_bsfs (FILE disk, superblock_t sb, const char path, const void data, uint32_t length)
	Overwrite an entire file with the provided buffer.
int	create_file_bsfs (FILE disk, superblock_t sb, const char *path)
	Create an empty regular file at `path`.
int	remove_file_bsfs (FILE disk, superblock_t sb, const char *path)
	Logically remove a file and move its snapshot into the Recovery tree.
int	move_bsfs (FILE disk, superblock_t sb, const char old_path, const char new_path)
	Move or rename an entry from `old_path` to `new_path`.
int	stat_bsfs (FILE disk, superblock_t sb, const char path, inode_t inode)
	Resolve `path` and return its inode metadata.
int	opendir_bsfs (FILE disk, superblock_t sb, const char dirname, dir_t dir)
	Open a directory for iteration.
int	closedir_bsfs (dir_t *dir)
	Close a directory descriptor (no-op for this API).
int	readdir_bsfs (FILE disk, superblock_t sb, dir_t dir, dir_entry_t entry)
	Read the next directory entry in key order.
int	mkdir_bsfs (FILE disk, superblock_t sb, const char *path)
	Create a new directory at `path`.
int	rmdir_bsfs (FILE disk, superblock_t sb, const char *path)
	Remove an empty directory at `path`.
int	chdir_bsfs (FILE disk, superblock_t sb, const char *path)
	Change the current working directory to `path`.
int	getcwd_bsfs (FILE disk, superblock_t sb, char *path_buffer, size_t buffer_size)
	Get the textual representation of the current working directory.
int	restore_bsfs (FILE disk, superblock_t sb, uint32_t recovery_id, const char *dest_dir)
	Restore a deleted file by recovery ID.
int	set_identity_bsfs (uint16_t uid, uint16_t gid)
	Set the current session identity (uid,gid) for permission checks.
int	get_identity_bsfs (uint16_t uid, uint16_t gid)
	Get the current session identity (uid,gid).
int	set_umask_bsfs (uint16_t umask)
	Set the current session umask (000..777).
int	get_umask_bsfs (uint16_t *umask)
	Get the current session umask.
int	chmod_bsfs (FILE disk, superblock_t sb, const char *path, uint16_t mode)
	Change permission bits of a path (octal 0000..7777).
int	chown_bsfs (FILE disk, superblock_t sb, const char *path, uint16_t uid)
	Change the owner (uid) of a path (root only).
int	chgrp_bsfs (FILE disk, superblock_t sb, const char *path, uint16_t gid)
	Change the group (gid) of a path (root only).

Detailed Description

High-level API used by the BSFS browser shell.

This header declares helper functions that wrap the internal BSFS operations (inode/directory/bspan B-trees) to provide a simple interface to the interactive browser. Functions support absolute and relative paths; when a relative path is provided, it is resolved against the in-memory current working directory maintained by the API.

Function Documentation

◆ chdir_bsfs()

int chdir_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path )

Change the current working directory to path.

Resolves the path, verifies it is a directory, and checks traverse permission for the current session identity.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Directory path.

Returns: 0 on success; -1 on error.

◆ chgrp_bsfs()

int chgrp_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path,
		uint16_t	gid )

Change the group (gid) of a path (root only).

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Target path.
gid	New group id.

Returns: 0 on success; -1 on error or permission denied.

◆ chmod_bsfs()

int chmod_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path,
		uint16_t	mode )

Change permission bits of a path (octal 0000..7777).

Allowed to root or file owner.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Target path.
mode	New mode bits (lowest 12 bits are honored).

Returns: 0 on success; -1 on error or permission denied.

◆ chown_bsfs()

int chown_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path,
		uint16_t	uid )

Change the owner (uid) of a path (root only).

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Target path.
uid	New owner user id.

Returns: 0 on success; -1 on error or permission denied.

◆ close_bsfs()

int close_bsfs ( file_t * file )

Close an open file descriptor (no-op in this API).

Metadata persistence is handled by write operations; closing does not flush any state and always succeeds.

Parameters

file	Open file descriptor (unused).

Returns: 0.

◆ closedir_bsfs()

int closedir_bsfs ( dir_t * dir )

Close a directory descriptor (no-op for this API).

Parameters

dir	Directory descriptor (unused).

Returns: 0.

◆ create_file_bsfs()

int create_file_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path )

Create an empty regular file at path.

Resolves the parent directory, checks modify permissions there, and creates a zero-length inode with owner/mode derived from the current session identity and umask.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Absolute or relative file path.

Returns: 0 on success; -1 on error (permissions, duplicates, or I/O).

◆ get_identity_bsfs()

int get_identity_bsfs	(	uint16_t *	uid,
		uint16_t *	gid )

Get the current session identity (uid,gid).

Parameters

uid	Output: current user id (nullable).
gid	Output: current group id (nullable).

Returns: 0.

◆ get_umask_bsfs()

int get_umask_bsfs ( uint16_t * umask )

Get the current session umask.

Parameters

umask Output: current umask (nullable).

Returns: 0.

◆ getcwd_bsfs()

int getcwd_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		char *	path_buffer,
		size_t	buffer_size )

Get the textual representation of the current working directory.

Parameters

disk	Unused.
sb	Unused.
path_buffer	Output buffer to receive the path.
buffer_size	Capacity of `path_buffer` (bytes).

Returns: 0 on success; -1 on invalid arguments.

◆ mkdir_bsfs()

int mkdir_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path )

Create a new directory at path.

Checks modify permissions on the parent and creates an empty directory with entries for "." and "..". Owner and mode are set from session identity and umask.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Directory path (absolute or relative).

Returns: 0 on success; -1 on error.

◆ move_bsfs()

int move_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	old_path,
		const char *	new_path )

Move or rename an entry from old_path to new_path.

Resolves source/destination parents, checks modify permissions on both and sticky-bit semantics on the source, then relinks the entry with the new name/location.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
old_path	Source path.
new_path	Destination path (may include a new basename).

Returns: 0 on success; -1 on error.

◆ open_bsfs()

int open_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path,
		file_t *	file )

Open a file by path and load its inode into a file_t.

Resolves path against the API's CWD, verifies that the target is a file or directory (permission checks for reading/writing are enforced later in read/write), and loads its inode into file with position set to 0.

Parameters

disk	Open filesystem image.
sb	Loaded superblock (inode tree root is used for lookups).
path	Absolute or relative path to the file.
file	Output: populated file descriptor snapshot.

Returns: 0 on success; -1 on failure.

◆ opendir_bsfs()

int opendir_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	dirname,
		dir_t *	dir )

Open a directory for iteration.

If dirname is NULL or ".", opens the current CWD after checking traverse and list permissions. Otherwise resolves dirname and verifies it is a directory and accessible.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
dirname	Directory path (NULL or "." means CWD).
dir	Output: directory descriptor snapshot.

Returns: 0 on success; -1 on error.

◆ overwrite_bsfs()

size_t overwrite_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path,
		const void *	data,
		uint32_t	length )

Overwrite an entire file with the provided buffer.

Opens path, seeks to 0, truncates to zero, and writes length bytes from data. Updates the inode metadata accordingly.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Target file path.
data	Buffer to write from.
length	Number of bytes to write.

Returns: Number of bytes written (0 on failure).

◆ read_bsfs()

size_t read_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		file_t *	file,
		void *	data,
		uint32_t	length )

Read up to length bytes from the current file position.

Performs a permission check (read) for the current session identity and reads data spanning direct and indirect block spans. Advances the file position by the number of bytes read.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
file	Open file descriptor.
data	Output buffer.
length	Maximum number of bytes to read.

Returns: Number of bytes read (0 on EOF or error).

◆ readdir_bsfs()

int readdir_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		dir_t *	dir,
		dir_entry_t *	entry )

Read the next directory entry in key order.

Uses the underlying B-tree iteration. Returns 1 when an entry is produced, 0 on end of directory, and -1 on invalid arguments.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
dir	Open directory descriptor.
entry	Output: next directory entry.

Returns: 1 on success, 0 on end, -1 on error.

◆ remove_file_bsfs()

int remove_file_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path )

Logically remove a file and move its snapshot into the Recovery tree.

Performs parent directory permissions and sticky-bit checks before unlinking the directory entry, removing the inode from the inode tree, and inserting a snapshot into the Recovery B-tree to allow later restore.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Target file path.

Returns: 0 on success; -1 on error.

◆ restore_bsfs()

int restore_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		uint32_t	recovery_id,
		const char *	dest_dir )

Restore a deleted file by recovery ID.

Loads the snapshot from the Recovery B-tree, chooses the destination directory (explicit, original parent, or CWD), recreates the inode and directory entry, and removes the snapshot. Restricted to root by default.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
recovery_id	Recovery entry identifier.
dest_dir	Optional destination directory path.

Returns: 0 on success; -1 on error or insufficient permission.

◆ rmdir_bsfs()

int rmdir_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path )

Remove an empty directory at path.

Verifies the target is a directory, checks parent modify permission and sticky-bit semantics, then removes the directory if it is empty.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Directory path to remove.

Returns: 0 on success; -1 on error.

◆ seek_bsfs()

int seek_bsfs	(	file_t *	file,
		uint32_t	pos )

Set the current file position (absolute) within the open file.

Fails if pos exceeds the current logical file size.

Parameters

file	Open file descriptor.
pos	New absolute byte position from the start of file.

Returns: 0 on success; -1 on invalid arguments or position.

◆ set_identity_bsfs()

int set_identity_bsfs	(	uint16_t	uid,
		uint16_t	gid )

Set the current session identity (uid,gid) for permission checks.

Parameters

uid	New user id.
gid	New group id.

Returns: 0.

◆ set_umask_bsfs()

int set_umask_bsfs ( uint16_t umask )

Set the current session umask (000..777).

Parameters

umask New umask in octal (lowest 9 bits are honored).

Returns: 0.

◆ stat_bsfs()

int stat_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		const char *	path,
		inode_t *	inode )

Resolve path and return its inode metadata.

Parameters

disk	Open filesystem image.
sb	Loaded superblock.
path	Absolute or relative path.
inode	Output: filled with the target's inode on success.

Returns: 0 on success; -1 if not found or invalid args.

◆ write_bsfs()

size_t write_bsfs	(	FILE *	disk,
		superblock_t *	sb,
		file_t *	file,
		void *	data,
		uint32_t	length )

Write length bytes from data at the current file position.

Allocates block spans as needed, writes the data, advances the file position, and persists the inode metadata update in the inode tree. Requires write permission for the current session identity.

Parameters

disk	Open filesystem image.
sb	Loaded superblock (used for allocation and inode updates).
file	Open file descriptor.
data	Input buffer containing bytes to write.
length	Number of bytes to write.

Returns: Number of bytes written (0 on error).