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 <kos/nmmgr.h>
#include <sys/fcntl.h>

Data Structures
struct	kos_dirent
	Directory entry. More...
struct	stat_t
	File status information. 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
#define	STAT_TYPE_NONE 0
	stat_t.type: Unknown / undefined / not relevant
#define	STAT_TYPE_FILE 1
	stat_t.type: Standard file
#define	STAT_TYPE_DIR 2
	stat_t.type: Standard directory
#define	STAT_TYPE_PIPE 3
	stat_t.type: A virtual device of some sort (pipe, socket, etc)
#define	STAT_TYPE_META 4
	stat_t.type: Meta data
#define	STAT_TYPE_SYMLINK 5
	stat_t.type: Symbolic link
#define	STAT_ATTR_NONE 0x00
	stat_t.attr: No attributes
#define	STAT_ATTR_R 0x01
	stat_t.attr: Read-capable
#define	STAT_ATTR_W 0x02
	stat_t.attr: Write-capable
#define	STAT_ATTR_RW (STAT_ATTR_R \| STAT_ATTR_W)
	stat_t.attr: Read/Write capable
#define	FILEHND_INVALID ((file_t)-1)
	Invalid file handle constant (for open failure, etc)
#define	FD_SETSIZE 1024
	The number of distinct file descriptors that can be in use at a time.
#define	O_MODE_MASK 0x0f
	Mask for mode numbers.
#define	O_ASYNC 0x0200
	Open for asynchronous I/O.
#define	O_DIR 0x1000
	Open as directory.
#define	O_META 0x2000
	Open as metadata.
#define	SEEK_SET 0
	Set position to offset.
#define	SEEK_CUR 1
	Seek from current position.
#define	SEEK_END 2
	Seek from end of file.

Typedefs
typedef struct kos_dirent	dirent_t
	Directory entry.
typedef int	file_t
	File descriptor type.
typedef struct vfs_handler	vfs_handler_t
	VFS handler interface.

Functions
file_t	fs_open (const char *fn, int mode)
	Open a file on the VFS.
int	fs_close (file_t hnd)
	Close an opened file.
ssize_t	fs_read (file_t hnd, void *buffer, size_t cnt)
	Read from an opened file.
ssize_t	fs_write (file_t hnd, const void *buffer, size_t cnt)
	Write to an opened file.
off_t	fs_seek (file_t hnd, off_t offset, int whence)
	Seek to a new position within a file.
_off64_t	fs_seek64 (file_t hnd, _off64_t offset, int whence)
	Seek to a new position within a file (64-bit offsets).
off_t	fs_tell (file_t hnd)
	Retrieve the position of the pointer within a file.
_off64_t	fs_tell64 (file_t hnd)
	Retrieve the position of the 64-bit pointer within a file.
size_t	fs_total (file_t hnd)
	Retrieve the length of an opened file.
uint64	fs_total64 (file_t hnd)
	Retrieve the length of an opened file as a 64-bit integer.
dirent_t *	fs_readdir (file_t hnd)
	Read an entry from an opened directory.
int	fs_ioctl (file_t hnd, void *data, size_t size)
	Execute a device-specific command on a file descriptor.
int	fs_rename (const char fn1, const char fn2)
	Rename the specified file to the given filename.
int	fs_unlink (const char *fn)
	Delete the specified file.
int	fs_chdir (const char *fn)
	Change the current working directory of the current thread.
void *	fs_mmap (file_t hnd)
	Memory-map a previously opened file.
int	fs_complete (file_t fd, ssize_t *rv)
	Perform an I/O completion on the given file descriptor.
int	fs_stat (const char fn, stat_t rv)
	Retrieve information about the specified path.
int	fs_mkdir (const char *fn)
	Create a directory.
int	fs_rmdir (const char *fn)
	Remove a directory by name.
int	fs_fcntl (file_t fd, int cmd,...)
	Manipulate file control flags.
int	fs_link (const char path1, const char path2)
	Create a hard link.
int	fs_symlink (const char path1, const char path2)
	Create a symbolic link.
file_t	fs_dup (file_t oldfd)
	Duplicate a file descriptor.
file_t	fs_dup2 (file_t oldfd, file_t newfd)
	Duplicate a file descriptor onto the specified descriptor.
file_t	fs_open_handle (vfs_handler_t vfs, void hnd)
	Create a "transient" file descriptor.
vfs_handler_t *	fs_get_handler (file_t fd)
	Retrieve the VFS Handler for a file descriptor.
void *	fs_get_handle (file_t fd)
	Retrieve the internal handle for a file descriptor.
const char *	fs_getwd ()
	Get the current working directory of the running thread.
ssize_t	fs_copy (const char src, const char dst)
	Copy a file.
ssize_t	fs_load (const char src, void *out_ptr)
	Open and read a whole file into RAM.
int	fs_init ()
	Initialize the virtual filesystem.
void	fs_shutdown ()
	Shut down the virtual filesystem.

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. Most filesystems do not support this operation on KallistiOS.

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.

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. Unlike most other VFS functions, this one does not set errno to ENOSYS in that case, but rather to EMLINK to preserve existing the original behavior in KOS.

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.

Note that some of the filesystems in KallistiOS do not support this operation.

Parameters:

hnd	The descriptor to memory map.

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

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_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.

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_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 *	fn,
		stat_t *	rv
	)

Retrieve information about the specified path.

This function retrieves the stat_t structure for the given path on the VFS. This function is similar to the standard POSIX function stat(), but provides slightly different data than it does.

Parameters:

fn	The path to retrieve information about.
rv	The buffer to store stat information in.

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.

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