shithub: dumb

ref: fb758de4fe3e5dcfa9f98bf65ff1be72ed9c678f
dir: /DUMBFILE_SYSTEM.md/

View raw version
Specification of DUMBFILE_SYSTEM
================================

DUMB is designed filesystem-agnostic, even though the C standard library
already defines an abstraction over files on a disk. This is useful because
Allegro 4 and 5 define their own abstractions.

To register your own filesystem abstraction with DUMB, you must create an
instance of struct `DUMBFILE_SYSTEM`, fill in your own function pointers
according to the specification below, and call `register_dumbfile_system` on
your instance.

The header `dumb.h` defines `DUMBFILE_SYSTEM` as a struct of function pointers:

```
typedef struct DUMBFILE_SYSTEM
{
    void *(*open)(const char *filename);
    int (*skip)(void *f, dumb_off_t n);
    int (*getc)(void *f);
    dumb_ssize_t (*getnc)(char *ptr, size_t n, void *f);
    void (*close)(void *f);
    int (*seek)(void *f, dumb_off_t n);
    dumb_off_t (*get_size)(void *f);
}
DUMBFILE_SYSTEM;
```

Here, `dumb_off_t` is a signed integer at least 64 bits wide, it is intended
to measure file offsets. The return type `dumb_ssize_t` is a signed integer
exactly as wide as `size_t`, it is intended to store either a `size_t` or a
negative error code. Both `dumb_*_t` are defined in `dumb.h`.

The function pointers `skip` and `getnc` are optional, i.e., you may set
some of these to `NULL` in your struct instance. DUMB will then try to
mimick the missing functions' behavior by calling your `getc` several times.
If DUMB is built with debugging flags, it will assert that all other
functions are not `NULL`. In release mode, DUMB will silently fail.

Your non-`NULL` function pointers must conform to the following specification.



open
----

```
void *(*open)(const char *filename);
```

Open a file for reading.

Arguments:

* `const char *filename`: A normal filename as understood by the operating
    system. Will be opened for reading.

Returns as `void *`:

* the address of a file handle on successfully opening the file.
    DUMB will pass this file handle as argument to other functions of
    the `DUMBFILE_SYSTEM`.

* `NULL` on error during opening the file.

Each file has a *position* internally managed by DUMB. A newly opened file
has a position of 0. Other functions from the `DUMBFILE_SYSTEM` can move
this position around.

DUMB allocates memory for the successfully opened file, and will store opaque
information in that memory, e.g., the DUMB-internal file position. This memory
be freed when DUMB calls `close` on the file's handle. The memory is separate
from your own filesystem implementation: You are responsible for supplying the
data, and DUMB is responsible for storing anything about interpreting that
data.



skip
----

```
int (*skip)(void *f, dumb_off_t n);
```

Advance the position in the file.

Arguments:

* `void *f`: A file handle that `open` returned. Guaranteed non-`NULL`.

* `dumb_off_t n`: Number of bytes to advance in the file. DUMB will only
call this with `n >= 0`. For `n < 0`, the behavior of `skip` is undefined.

Returns as `int`:

* `0` on successfully skipping ahead by `n` bytes.

* `-1` on error.

It is legal to set `skip = NULL` in a `DUMBFILE_SYSTEM`. DUMB will then call
`getc` a total of `n` times to skip ahead in a file. For speed, it is
advisable to supply a proper `skip` implementation.



getc
----

```
int (*getc)(void *f);
```

Read a byte from the file.

Arguments:

* `void *f`: A file handle that `open` returned. Guaranteed non-`NULL`.

Returns as `int`:

* the value of the byte read, on successfully reading one byte.

* `-1` on error.

After a succesful read, DUMB will treat the file as advanced by one byte.



getnc
-----

```
dumb_ssize_t (*getnc)(char *ptr, size_t n, void *f);
```

Read up to the given number of bytes from the file into a given buffer.

* `char *ptr`: The start of a buffer provided by DUMB.

* `size_t n`: The length of the number of bytes to be read.

* `void *f`: A file handle that `open` returned. Guaranteed non-`NULL`.

Returns as `dumb_ssize_t`:

* the number of bytes successfully read, if it was possible to read at least
one byte.

* `-1` on error, when it was not possible to read even a single byte.

This function shall bytes from the file `f` and store them in sequence in the
buffer beginning at `ptr`. It shall read fewer than `n` bytes if end of file
is encountered before `n` bytes could have been read, otherwise it should read
`n` bytes.

It is legal to set `skip = NULL` in a `DUMBFILE_SYSTEM`. DUMB will then call
`getc` a total of `n` times and store the results in its buffer.



close
-----

```
void (*close)(void *f);
```

Closes a file that has been opened before with `open`.

Arguments:

* `void *f`: A file handle that `open` returned. Guaranteed non-`NULL`.

DUMB will deallocate the memory that it used to interpret the file. You are
free to treat your resource however you would like: You may deallocate it, or
keep it around for other things. For example, Allegro 5's implementation
of `close` takes a void pointer and does nothing with it at all.



seek
----

```
int (*seek)(void *f, dumb_off_t n);
```

Jump to an arbitrary position in the file.

Arguments:

* `void *f`: A file handle that `open` returned. Guaranteed non-`NULL`.

* `dumb_off_t n`: The position in the file, relative to the beginning.
    There is no guarantee whether `n >= 0`.

Returns as `int`:

* `0` on successfully seeking in the file.

* `-1` on error.

DUMB will modify its internal position of the file accordingly.

A value of `n < 0` shall set the file into an erroneous state from which no
bytes can be read.



get_size
--------

```
dumb_off_t (*get_size)(void *f);
```

Get the length in bytes, i.e., the position after the final byte, of a file.

Arguments:

* `void *f`: A file handle that `open` returned. Guaranteed non-`NULL`.

Returns as `dumb_off_t`:

* the length of the file in bytes.