Struct Api

#[repr(C)]
pub struct Api {

    pub open: extern "C" fn(path: FfiString<'_>, flags: Flags) -> Result<Handle>,
    pub close: extern "C" fn(fd: Handle) -> Result<()>,
    pub write: extern "C" fn(fd: Handle, buffer: FfiByteSlice<'_>) -> Result<()>,
    pub read: extern "C" fn(fd: Handle, buffer: FfiBuffer<'_>) -> Result<usize>,
    pub seek_set: extern "C" fn(fd: Handle, position: u64) -> Result<()>,
    pub seek_cur: extern "C" fn(fd: Handle, offset: i64) -> Result<u64>,
    pub seek_end: extern "C" fn(fd: Handle) -> Result<u64>,
    pub rename: extern "C" fn(old_path: FfiString<'_>, new_path: FfiString<'_>) -> Result<()>,
    pub ioctl: extern "C" fn(fd: Handle, command: u64, value: u64) -> Result<u64>,
    pub opendir: extern "C" fn(path: FfiString<'_>) -> Result<Handle>,
    pub closedir: extern "C" fn(dir: Handle) -> Result<()>,
    pub readdir: extern "C" fn(dir: Handle) -> Result<Entry>,
    pub stat: extern "C" fn(path: FfiString<'_>) -> Result<Stat>,
    pub fstat: extern "C" fn(fd: Handle) -> Result<Stat>,
    pub deletefile: extern "C" fn(path: FfiString<'_>) -> Result<()>,
    pub deletedir: extern "C" fn(path: FfiString<'_>) -> Result<()>,
    pub chdir: extern "C" fn(path: FfiString<'_>) -> Result<()>,
    pub dchdir: extern "C" fn(dir: Handle) -> Result<()>,
    pub pwd: extern "C" fn(path: FfiBuffer<'_>) -> Result<usize>,
    pub malloc: extern "C" fn(size: usize, alignment: usize) -> Result<*mut c_void>,
    pub free: extern "C" fn(ptr: *mut c_void, size: usize, alignment: usize),
}

The syscalls provided by the Neotron OS to a Neotron Application.

Fields

open: extern "C" fn(path: FfiString<'_>, flags: Flags) -> Result<Handle>

Open a file, given a path as UTF-8 string.

If the file does not exist, or is already open, it returns an error.

Path may be relative to current directory, or it may be an absolute path.

Limitations

• You cannot open a file if it is currently open.
• Paths must confirm to the rules for the filesystem for the given drive.
• Relative paths are taken relative to the current directory (see Api::chdir).

close: extern "C" fn(fd: Handle) -> Result<()>

Close a previously opened file.

Closing a file is important, as only this action will cause the directory entry for the file to be updated. Crashing the system without closing a file may cause the directory entry to be incorrect, and you may need to run CHKDSK (or similar) on your disk to fix it.

write: extern "C" fn(fd: Handle, buffer: FfiByteSlice<'_>) -> Result<()>

Write to an open file handle, blocking until everything is written.

Some files do not support writing and will produce an error. You will also get an error if you run out of disk space.

The buffer is only borrowed for the duration of the function call and is then forgotten.

read: extern "C" fn(fd: Handle, buffer: FfiBuffer<'_>) -> Result<usize>

Read from an open file, returning how much was actually read.

You might get less data than you asked for. If you do an Api::read and you are already at the end of the file you will get Err(Error::EndOfFile).

Data is stored to the given buffer. The buffer` is only borrowed for the duration of the function call and is then forgotten.

seek_set: extern "C" fn(fd: Handle, position: u64) -> Result<()>

Move the file offset (for the given file handle) to the given position.

Some files do not support seeking and will produce an error.

seek_cur: extern "C" fn(fd: Handle, offset: i64) -> Result<u64>

Move the file offset (for the given file handle) relative to the current position.

Returns the new file offset.

Some files do not support seeking and will produce an error.

seek_end: extern "C" fn(fd: Handle) -> Result<u64>

Move the file offset (for the given file handle) to the end of the file

Returns the new file offset.

Some files do not support seeking and will produce an error.

rename: extern "C" fn(old_path: FfiString<'_>, new_path: FfiString<'_>) -> Result<()>

Rename a file.

Limitations

• You cannot rename a file if it is currently open.
• You cannot rename a file where the old_path and the new_path are not on the same drive.
• Paths must confirm to the rules for the filesystem for the given drive.

ioctl: extern "C" fn(fd: Handle, command: u64, value: u64) -> Result<u64>

Perform a special I/O control operation.

opendir: extern "C" fn(path: FfiString<'_>) -> Result<Handle>

Open a directory, given a path as a UTF-8 string.

closedir: extern "C" fn(dir: Handle) -> Result<()>

Close a previously opened directory.

readdir: extern "C" fn(dir: Handle) -> Result<Entry>

Read from an open directory

stat: extern "C" fn(path: FfiString<'_>) -> Result<Stat>

Get information about a file.

fstat: extern "C" fn(fd: Handle) -> Result<Stat>

Get information about an open file.

deletefile: extern "C" fn(path: FfiString<'_>) -> Result<()>

Delete a file.

Limitations

• You cannot delete a file if it is currently open.

deletedir: extern "C" fn(path: FfiString<'_>) -> Result<()>

Delete a directory.

Limitations

• You cannot delete a root directory.
• You cannot delete a directory that has any files or directories in it.

chdir: extern "C" fn(path: FfiString<'_>) -> Result<()>

Change the current directory.

Relative file paths (e.g. passed to Api::open) are taken to be relative to the current directory.

Unlike on MS-DOS, there is only one current directory for the whole system, not one per drive.

dchdir: extern "C" fn(dir: Handle) -> Result<()>

Change the current directory to the given open directory.

Unlike on MS-DOS, there is only one current directory for the whole system, not one per drive.

pwd: extern "C" fn(path: FfiBuffer<'_>) -> Result<usize>

Get the current directory.

The current directory is stored as UTF-8 into the given buffer. The function returns the number of bytes written to the buffer, or an error. If the function did not return an error, the buffer can be assumed to contain a valid file path. That path will not be null terminated.

malloc: extern "C" fn(size: usize, alignment: usize) -> Result<*mut c_void>

Allocate some memory.

• size - the number of bytes required
• alignment - the returned address will have this alignment, or better. For example, pass 4 if you are allocating an array of u32.

free: extern "C" fn(ptr: *mut c_void, size: usize, alignment: usize)

Free some previously allocated memory.

You must pass the same size and alignment values that you passed to malloc.