Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
stream_spans.c

Spans: give a parser a range of a stream it cannot read past.

Spans: give a parser a range of a stream it cannot read past.File formats hold tables at offsets: a font file holds its glyph table here, its metrics there. A span turns one range of a stream into a stream of its own, checked once when it is created. From then on, a parser that trusts a corrupt length still cannot read a byte of the next table: the span stops at its end, and bj_stream_peek answers 0 rather than a pointer past it.

What you'll learn

  • bj_create_stream_span, and why its bounds are checked once.
  • That a span has its own cursor, and never moves its parent's.
  • bj_stream_peek on a span, and the 0 it gives out of range.
#include <banjo/log.h>
#include <banjo/main.h>
#include <banjo/stream.h>
int main(int argc, char* argv[]) {
(void)argc; (void)argv;
// A "file" of three tables, 4 bytes each: HEAD, NAME, DATA.
static const char file_bytes[] = "HEADname1234";
// The NAME table: 4 bytes at offset 4. An out-of-range table, as a
// corrupt directory would declare, gives 0 here, once.
bj_stream* name = bj_create_stream_span(file, 4, 4);
bj_stream* broken = bj_create_stream_span(file, 10, 8);
bj_info("Span of NAME: %s; span of 8 bytes at 10: %s",
name != 0 ? "created" : "refused", broken != 0 ? "created" : "refused");
if (name == 0) {
return 1;
}
// A parser asks for 8 bytes, believing a wrong length: it gets the 4
// bytes of NAME, and the status says the table ended.
char buffer[9] = {0};
const size_t got = bj_read_stream(name, buffer, 8);
bj_info("Asked 8 bytes, got %zu: \"%s\", %s", got, buffer,
bj_stream_status(name) == BJ_STREAM_STATUS_END ? "end of the table" : "?");
// Peeking inside the span works; peeking past it gives 0.
const char* inside = (const char*)bj_stream_peek(name, 1, 2);
const void* outside = bj_stream_peek(name, 3, 2);
bj_info("Peek of 2 bytes at 1: \"%.2s\"; at 3: %s", inside, outside == 0 ? "0" : "a pointer");
// The parent's cursor never moved.
bj_info("The file's cursor is still at %zu", bj_stream_position(file));
// Spans borrow their parent: destroy them first. Destroying 0, the
// refused span, does nothing.
return 0;
}
struct bj_stream bj_stream
Definition api.h:374
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
const void * bj_stream_peek(struct bj_stream *stream, size_t offset, size_t length)
Points at bytes of the stream without moving the cursor.
void bj_destroy_stream(struct bj_stream *stream)
Destroy a stream and release its memory.
size_t bj_stream_position(struct bj_stream *stream)
Return the current cursor position within the stream.
struct bj_stream * bj_create_stream_span(struct bj_stream *parent, size_t offset, size_t length)
Create a span over the range [offset, offset + length) of another stream.
struct bj_stream * bj_create_stream_from_read_memory(const void *data, size_t length)
Create a read-only stream that reads from an in-memory buffer.
bj_stream_status
Why the last read or write of a stream fell short.
Definition stream.h:150
size_t bj_read_stream(struct bj_stream *stream, void *dest, size_t count)
Reads data from the stream into a destination buffer.
@ BJ_STREAM_STATUS_END
The data ran out, or a fixed-size stream is full.
Definition stream.h:152
Logging utility functions.
Portable main() replacement with platform-aware entry shim.
Header file for struct bj_stream struct and related functions.
int main(void)