Virtual filesystem support. More...

#include <sys/cdefs.h>
#include <sys/types.h>
#include <kos/limits.h>
#include <time.h>
#include <sys/queue.h>
#include <stdarg.h>
#include <sys/stat.h>
#include <kos/nmmgr.h>
#include <sys/fcntl.h>

Data Structures
struct	kos_dirent
	Directory entry. More...

struct	vfs_handler
	VFS handler interface. More...

Macros
#define	STAT_UNIQUE_NONE 0
	stat_t.unique: Constant to use denoting the file has no unique ID More...

#define	STAT_TYPE_NONE 0
	stat_t.type: Unknown / undefined / not relevant More...

#define	STAT_TYPE_FILE 1
	stat_t.type: Standard file More...

#define	STAT_TYPE_DIR 2
	stat_t.type: Standard directory More...

#define	STAT_TYPE_PIPE 3
	stat_t.type: A virtual device of some sort (pipe, socket, etc) More...

#define	STAT_TYPE_META 4
	stat_t.type: Meta data More...

#define	STAT_TYPE_SYMLINK 5
	stat_t.type: Symbolic link More...

#define	STAT_ATTR_NONE 0x00
	stat_t.attr: No attributes More...

#define	STAT_ATTR_R 0x01
	stat_t.attr: Read-capable More...

#define	STAT_ATTR_W 0x02
	stat_t.attr: Write-capable More...

#define	STAT_ATTR_RW (STAT_ATTR_R \| STAT_ATTR_W)
	stat_t.attr: Read/Write capable More...

#define	FILEHND_INVALID ((file_t)-1)
	Invalid file handle constant (for open failure, etc) More...

#define	FD_SETSIZE 1024
	The number of distinct file descriptors that can be in use at a time. More...

#define	O_MODE_MASK 0x0f
	Mask for mode numbers. More...

#define	O_ASYNC 0x0200
	Open for asynchronous I/O. More...

#define	O_DIR 0x1000
	Open as directory. More...

#define	O_META 0x2000
	Open as metadata. More...

#define	SEEK_SET 0
	Set position to offset. More...

#define	SEEK_CUR 1
	Seek from current position. More...

#define	SEEK_END 2
	Seek from end of file. More...

Typedefs
typedef struct kos_dirent	dirent_t
	Directory entry. More...

typedef int	file_t
	File descriptor type. More...

typedef struct vfs_handler	vfs_handler_t
	VFS handler interface. More...

Functions
file_t	fs_open (const char *fn, int mode)
	Open a file on the VFS. More...

int	fs_close (file_t hnd)
	Close an opened file. More...

ssize_t	fs_read (file_t hnd, void *buffer, size_t cnt)
	Read from an opened file. More...

ssize_t	fs_write (file_t hnd, const void *buffer, size_t cnt)
	Write to an opened file. More...

off_t	fs_seek (file_t hnd, off_t offset, int whence)
	Seek to a new position within a file. More...

_off64_t	fs_seek64 (file_t hnd, _off64_t offset, int whence)
	Seek to a new position within a file (64-bit offsets). More...

off_t	fs_tell (file_t hnd)
	Retrieve the position of the pointer within a file. More...

_off64_t	fs_tell64 (file_t hnd)
	Retrieve the position of the 64-bit pointer within a file. More...

size_t	fs_total (file_t hnd)
	Retrieve the length of an opened file. More...

uint64	fs_total64 (file_t hnd)
	Retrieve the length of an opened file as a 64-bit integer. More...

dirent_t *	fs_readdir (file_t hnd)
	Read an entry from an opened directory. More...

int	fs_ioctl (file_t hnd, void *data, size_t size)
	Execute a device-specific command on a file descriptor. More...

int	fs_rename (const char fn1, const char fn2)
	Rename the specified file to the given filename. More...

int	fs_unlink (const char *fn)
	Delete the specified file. More...

int	fs_chdir (const char *fn)
	Change the current working directory of the current thread. More...

void *	fs_mmap (file_t hnd)
	Memory-map a previously opened file. More...

int	fs_complete (file_t fd, ssize_t *rv)
	Perform an I/O completion on the given file descriptor. More...

int	fs_mkdir (const char *fn)
	Create a directory. More...

int	fs_rmdir (const char *fn)
	Remove a directory by name. More...

int	fs_fcntl (file_t fd, int cmd,...)
	Manipulate file control flags. More...

int	fs_link (const char path1, const char path2)
	Create a hard link. More...

int	fs_symlink (const char path1, const char path2)
	Create a symbolic link. More...

ssize_t	fs_readlink (const char path, char buf, size_t bufsize)
	Read the value of a symbolic link. More...

int	fs_stat (const char path, struct stat buf, int flag)
	Retrieve information about the specified path. More...

int	fs_rewinddir (file_t hnd)
	Rewind a directory to the start. More...

file_t	fs_dup (file_t oldfd)
	Duplicate a file descriptor. More...

file_t	fs_dup2 (file_t oldfd, file_t newfd)
	Duplicate a file descriptor onto the specified descriptor. More...

file_t	fs_open_handle (vfs_handler_t vfs, void hnd)
	Create a "transient" file descriptor. More...

vfs_handler_t *	fs_get_handler (file_t fd)
	Retrieve the VFS Handler for a file descriptor. More...

void *	fs_get_handle (file_t fd)
	Retrieve the internal handle for a file descriptor. More...

const char *	fs_getwd ()
	Get the current working directory of the running thread. More...

ssize_t	fs_copy (const char src, const char dst)
	Copy a file. More...

ssize_t	fs_load (const char src, void *out_ptr)
	Open and read a whole file into RAM. More...

ssize_t	fs_path_append (char dst, const char src, size_t len)
	Append a path component to a string. More...

int	fs_init ()
	Initialize the virtual filesystem. More...

void	fs_shutdown ()
	Shut down the virtual filesystem. More...

Detailed Description

Virtual filesystem support.

This file contains the interface to the virtual filesystem (VFS) of KOS. The functions defined in this file make up the base of the filesystem operations that can be performed by programs. The functions in here are abstracted by various other layers in libc, and shouldn't be necessarily used (for portability reasons). However, if you want only to interact with KOS in your programs, feel free to use them to your heart's content!

Author: Dan Potter; Lawrence Sebald

Macro Definition Documentation

#define FD_SETSIZE 1024

The number of distinct file descriptors that can be in use at a time.

#define FILEHND_INVALID ((file_t)-1)

Invalid file handle constant (for open failure, etc)

#define STAT_ATTR_NONE 0x00

stat_t.attr: No attributes

#define STAT_ATTR_R 0x01

stat_t.attr: Read-capable

#define STAT_ATTR_RW (STAT_ATTR_R | STAT_ATTR_W)

stat_t.attr: Read/Write capable

#define STAT_ATTR_W 0x02

stat_t.attr: Write-capable

#define STAT_TYPE_DIR 2

stat_t.type: Standard directory

#define STAT_TYPE_FILE 1

stat_t.type: Standard file

#define STAT_TYPE_META 4

stat_t.type: Meta data

#define STAT_TYPE_NONE 0

stat_t.type: Unknown / undefined / not relevant

#define STAT_TYPE_PIPE 3

stat_t.type: A virtual device of some sort (pipe, socket, etc)

#define STAT_TYPE_SYMLINK 5

stat_t.type: Symbolic link

#define STAT_UNIQUE_NONE 0

stat_t.unique: Constant to use denoting the file has no unique ID

<

Typedef Documentation

typedef struct kos_dirent dirent_t

Directory entry.

All VFS handlers must conform to this interface in their directory entries.

typedef int file_t

File descriptor type.

typedef struct vfs_handler vfs_handler_t

VFS handler interface.

All VFS handlers must implement this interface.

Function Documentation

int fs_chdir ( const char * fn )

Change the current working directory of the current thread.

This function changes the current working directory for the current thread. Any relative paths passed into file-related functions will be relative to the path that is changed to.

Parameters

fn	The path to set as the current working directory.

Returns: 0 on success, -1 on failure.

int fs_close ( file_t hnd )

Close an opened file.

This function closes the specified file descriptor, releasing all resources associated with the descriptor.

Parameters

hnd	The file descriptor to close.

Returns: 0 for success, -1 for error

int fs_complete	(	file_t	fd,
		ssize_t *	rv
	)

Perform an I/O completion on the given file descriptor.

This function is used with asynchronous I/O to perform an I/O completion on the given file descriptor.

Parameters

fd	The descriptor to complete I/O on.
rv	A buffer to store the size of the I/O in.

Returns: 0 on success, -1 on failure.

Note: Most of the filesystems in KallistiOS do not support this operation. If you attempt to use this function on a filesystem that does not support it, the function will return -1 and set errno to EINVAL.

ssize_t fs_copy	(	const char *	src,
		const char *	dst
	)

Copy a file.

This function copies the file at src to dst on the filesystem.

Parameters

src	The filename to copy from.
dst	The filename to copy to.

Returns: The number of bytes copied successfully.

file_t fs_dup ( file_t oldfd )

Duplicate a file descriptor.

This function duplicates the specified file descriptor, returning a new file descriptor that can be used to access the file. This is equivalent to the standard POSIX function dup().

Parameters

oldfd The old file descriptor to duplicate.

Returns: The new file descriptor on success, -1 on failure.

file_t fs_dup2	(	file_t	oldfd,
		file_t	newfd
	)

Duplicate a file descriptor onto the specified descriptor.

This function duplicates the specified file descriptor onto the other file descriptor provided. If the newfd parameter represents an open file, that file will be closed before the old descriptor is duplicated onto it. This is equivalent to the standard POSIX function dup2().

Parameters

oldfd	The old file descriptor to duplicate.
newfd	The descriptor to copy into.

Returns: The new file descriptor on success, -1 on failure.

int fs_fcntl	(	file_t	fd,
		int	cmd,
			...
	)

Manipulate file control flags.

This function implements the standard C fcntl function.

Parameters

fd	The file descriptor to use.
cmd	The command to run.
...	Arguments for the command specified.

Returns: -1 on error (generally).

void* fs_get_handle ( file_t fd )

Retrieve the internal handle for a file descriptor.

This function retrieves the internal file handle data of the specified file descriptor. There is generally no reason to call this function in user code, as it is meant for use internally.

Parameters

fd	The file descriptor to retrieve the handler for.

Returns: The internal handle for the file descriptor.

vfs_handler_t* fs_get_handler ( file_t fd )

Retrieve the VFS Handler for a file descriptor.

This function retrieves the Handler structure for the VFS of the specified file descriptor. There is generally no reason to call this function in user code, as it is meant for use internally.

Parameters

fd	The file descriptor to retrieve the handler for.

Returns: The VFS' handler structure.

const char* fs_getwd ( )

Get the current working directory of the running thread.

Returns: The current working directory.

int fs_init ( )

Initialize the virtual filesystem.

This is normally done for you by default when KOS starts. In general, there should be no reason for you to call this function.

Return values

0	On success.

int fs_ioctl	(	file_t	hnd,
		void *	data,
		size_t	size
	)

Execute a device-specific command on a file descriptor.

The types and formats of the commands are device/filesystem specific, and are not documented here. Each filesystem may define any commands that are specific to it with its implementation of this function.

Parameters

hnd	The file descriptor to operate on.
data	The command to send.
size	The size of the command, in bytes.

Returns: -1 on failure.

int fs_link	(	const char *	path1,
		const char *	path2
	)

Create a hard link.

This function implements the POSIX function link(), which creates a hard link for an existing file.

Parameters

path1	An existing file to create a new link to.
path2	The pathname of the new link to be created.

Returns: 0 on success, -1 on failure.

Note: Most filesystems in KallistiOS do not support hard links. If you call this function on a filesystem that does not support hard links, the function will return -1 and set errno to EMLINK.

ssize_t fs_load	(	const char *	src,
		void **	out_ptr
	)

Open and read a whole file into RAM.

This function opens the specified file, reads it into memory (allocating the necessary space with malloc), and closes the file. The caller is responsible for freeing the memory when they are done with it.

Parameters

src	The filename to open and read.
out_ptr	A pointer to the buffer on success, NULL otherwise.

Returns: The size of the file on success, -1 otherwise.

int fs_mkdir ( const char * fn )

Create a directory.

This function creates the specified directory, if possible.

Parameters

fn	The path of the directory to create.

Returns: 0 on success, -1 on failure.

void* fs_mmap ( file_t hnd )

Memory-map a previously opened file.

This file "maps" the opened file into memory, reading the whole file into a buffer, and returning that buffer. The returned buffer should not be freed, as it will be freed when the file is closed. Bytes written into the buffer, up to the original length of the file, will be written back to the file when it is closed, assuming that the file is opened for writing.

Parameters

hnd	The descriptor to memory map.

Returns: The memory mapped buffer, or NULL on failure.

Note: Some of the filesystems in KallistiOS do not support this operation. If you attempt to use this function on a filesystem that does not support it, the function will return NULL and set errno to EINVAL.

file_t fs_open	(	const char *	fn,
		int	mode
	)

Open a file on the VFS.

This function opens the specified file, returning a new file descriptor to access the file.

Parameters

fn	The path to open.
mode	The mode to use with opening the file. This may include the standard open modes (O_RDONLY, O_WRONLY, etc), as well as values from the File open modes list. Multiple values can be ORed together.

Returns: The new file descriptor on success, -1 on error.

file_t fs_open_handle	(	vfs_handler_t *	vfs,
		void *	hnd
	)

Create a "transient" file descriptor.

This function creates and opens a new file descriptor that isn't associated directly with a file on the filesystem. This is used internally to actually open files, and should (in general) not be called by user code. Effectively, if you're trying to implement your own filesystem handler in your code, you may need this function, otherwise you should just ignore it.

Parameters

vfs	The VFS handler structure to use for the file.
hnd	Internal handle data for the file.

Returns: The opened descriptor on success, -1 on failure.

ssize_t fs_path_append	(	char *	dst,
		const char *	src,
		size_t	len
	)

Append a path component to a string.

This function acts mostly like the function strncat(), with a few slight differences. First, if the destination string doesn't end in a '/' character, this function will add it. Second, it returns the length of the resulting string, including the NUL terminator. Finally, no modification of the destination string will occur if there isn't enough space left in the string to do so.

Parameters

dst	The string to modify.
src	The path component to append.
len	The length allocated for dst.

Returns: The length of the new string (including the NUL terminator) on success, -1 otherwise.

Error Conditions:: EFAULT - src or dst is a NULL pointer
EINVAL - len is zero
ENAMETOOLONG - the resulting path would be longer than len bytes

ssize_t fs_read	(	file_t	hnd,
		void *	buffer,
		size_t	cnt
	)

Read from an opened file.

This function reads into the specified buffer from the file at its current file pointer.

Parameters

hnd	The file descriptor to read from.
buffer	The buffer to read into.
cnt	The size of the buffer (or the number of bytes requested).

Returns: The number of bytes read, or -1 on error. Note that this may not be the full number of bytes requested.

dirent_t* fs_readdir ( file_t hnd )

Read an entry from an opened directory.

This function reads the next entry from the directory specified by the given file descriptor.

Parameters

hnd	The opened directory's file descriptor.

Returns: The next entry, or NULL on failure.

ssize_t fs_readlink	(	const char *	path,
		char *	buf,
		size_t	bufsize
	)

Read the value of a symbolic link.

This function implements the POSIX function readlink(), which simply reads the value of the symbolic link at the end of a path. This does not resolve any internal links and it does not canonicalize the path either.

Parameters

path	The symbolic link to read.
buf	The buffer to place the link's contents in.
bufsize	The number of bytes allocated to buf.

Returns: -1 on failure, the number of bytes placed into buf on success. If the return value is equal to bufsize, you may not have the whole link – provide a larger buffer and try again.

Note: Most filesystems in KallistiOS do not support symbolic links. Filesystems that do not support symlinks will simply set errno to ENOSYS and return -1.

int fs_rename	(	const char *	fn1,
		const char *	fn2
	)

Rename the specified file to the given filename.

This function renames the file specified by the first argument to the second argument. The two paths should be on the same filesystem.

Parameters

fn1	The existing file to rename.
fn2	The new filename to rename to.

Returns: 0 on success, -1 on failure.

int fs_rewinddir ( file_t hnd )

Rewind a directory to the start.

This function rewinds the position of a directory stream to the beginning of the directory.

Parameters

hnd	The opened directory's file descriptor.

Returns: 0 on success, -1 on failure.

Note: Some filesystems may not support this function. If a filesystem doesn't support it, errno will be set to ENOSYS and -1 will be returned.

int fs_rmdir ( const char * fn )

Remove a directory by name.

This function removes the specified directory. The directory shall only be removed if it is empty.

Parameters

fn	The path of the directory to remove.

Returns: 0 on success, -1 on failure.

off_t fs_seek	(	file_t	hnd,
		off_t	offset,
		int	whence
	)

Seek to a new position within a file.

This function moves the file pointer to the specified position within the file (the base of this position is determined by the whence parameter).

Parameters

hnd	The file descriptor to move the pointer for.
offset	The offset in bytes from the specified base.
whence	The base of the pointer move. This should be one of the Seek modes values.

Returns: The new position of the file pointer.

_off64_t fs_seek64	(	file_t	hnd,
		_off64_t	offset,
		int	whence
	)

Seek to a new position within a file (64-bit offsets).

This function moves the file pointer to the specified position within the file (the base of this position is determined by the whence parameter).

Parameters

hnd	The file descriptor to move the pointer for.
offset	The offset in bytes from the specified base.
whence	The base of the pointer move. This should be one of the Seek modes values.

Returns: The new position of the file pointer.

void fs_shutdown ( )

Shut down the virtual filesystem.

This is done for you by the normal shutdown procedure of KOS. There should not really be any reason for you to call this function yourself.

int fs_stat	(	const char *	path,
		struct stat *	buf,
		int	flag
	)

Retrieve information about the specified path.

This function retrieves status information on the given path. This function now returns the normal POSIX-style struct stat, rather than the old KOS stat_t structure. In addition, you can specify whether or not this function should resolve symbolic links on filesystems that support symlinks.

Parameters

path	The path to retrieve information about.
buf	The buffer to store stat information in.
flag	Specifies whether or not to resolve a symbolic link. If you don't want to resolve any symbolic links at the end of the path, pass AT_SYMLINK_NOFOLLOW, otherwise pass 0.

Returns: 0 on success, -1 on failure.

int fs_symlink	(	const char *	path1,
		const char *	path2
	)

Create a symbolic link.

This function implements the POSIX function symlink(), which creates a symbolic link on the filesystem. Symbolic links are not required to point to an existing file (per POSIX) and may result in circular links if care is not taken. For now, symbolic links cannot cross filesystem boundaries in KOS.

Parameters

path1	The content of the link (i.e, what to point at).
path2	The pathname of the new link to be created.

Returns: 0 on success, -1 on failure.

Note: Most filesystems in KallistiOS do not support symbolic links. Filesystems that do not support symlinks will simply set errno to ENOSYS and return -1.

off_t fs_tell ( file_t hnd )

Retrieve the position of the pointer within a file.

This function retrieves the current location of the file pointer within an opened file. This is an offset in bytes from the start of the file.

Parameters

hnd	The file descriptor to retrieve the pointer from.

Returns: The offset within the file for the pointer.

_off64_t fs_tell64 ( file_t hnd )

Retrieve the position of the 64-bit pointer within a file.

This function retrieves the current location of the file pointer within an opened file. This is an offset in bytes from the start of the file.

Parameters

hnd	The file descriptor to retrieve the pointer from.

Returns: The offset within the file for the pointer.

size_t fs_total ( file_t hnd )

Retrieve the length of an opened file.

This file retrieves the length of the file associated with the given file descriptor.

Parameters

hnd	The file descriptor to retrieve the size from.

Returns: The length of the file on success, -1 on failure.

uint64 fs_total64 ( file_t hnd )

Retrieve the length of an opened file as a 64-bit integer.

This file retrieves the length of the file associated with the given file descriptor.

Parameters

hnd	The file descriptor to retrieve the size from.

Returns: The length of the file on success, -1 on failure.

int fs_unlink ( const char * fn )

Delete the specified file.

This function deletes the specified file from the filesystem. This should only be used for files, not for directories. For directories, use fs_rmdir() instead of this function.

Parameters

fn	The path to remove.

Returns: 0 on success, -1 on failure.

ssize_t fs_write	(	file_t	hnd,
		const void *	buffer,
		size_t	cnt
	)

Write to an opened file.

This function writes the specfied buffer into the file at the current file pointer.

Parameters

hnd	The file descriptor to write into.
buffer	The data to write into the file.
cnt	The size of the buffer, in bytes.

Returns: The number of bytes written, or -1 on failure. Note that the number of bytes written may be less than what was requested.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation