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

File streams: write a file, append to it, then read it by chunks without loading it.

File streams: write a file, append to it, then read it by chunks without loading it.A file stream reads and writes on demand: it never loads the whole file, so a 10 GB file costs what you read of it. Flags say what the stream is opened for, as the modes of fopen do, and a file opened only for reading is mapped into memory, so the system pages it in as you go.

What you'll learn

#include <banjo/log.h>
#include <banjo/main.h>
#include <banjo/stream.h>
#include <banjo/string.h>
#include <stdio.h>
#include <string.h>
#define PATH "stream_file_example.txt"
static bj_bool write_text(const char* text, uint32_t flags) {
bj_error* error = 0;
bj_stream* file = bj_create_stream_from_path(BJ_STR(PATH), flags, &error);
if (file == 0) {
bj_err("Cannot open %s: %s", PATH, bj_error_message(error));
bj_clear_error(&error);
return BJ_FALSE;
}
const size_t length = strlen(text);
const bj_bool done = bj_write_stream(file, text, length) == length;
return done;
}
int main(int argc, char* argv[]) {
(void)argc; (void)argv;
// "w": create the file, or empty it. Then "a": every write goes to the
// end, wherever the cursor stands.
if (!write_text("Banjo streams read files\n", BJ_STREAM_WRITE | BJ_STREAM_CREATE | BJ_STREAM_TRUNCATE)
|| !write_text("on demand, chunk by chunk.\n", BJ_STREAM_WRITE | BJ_STREAM_CREATE | BJ_STREAM_APPEND)) {
return 1;
}
// "r": a read-only stream, mapped where the platform allows it.
bj_error* error = 0;
if (file == 0) {
bj_err("Cannot read %s: %s", PATH, bj_error_message(error));
bj_clear_error(&error);
return 1;
}
bj_info("%s: %zu bytes, mapped: %s", PATH, bj_stream_length(file),
bj_stream_is_mapped(file) ? "yes" : "no");
// Read 16 bytes at a time: a short read means the status has the reason.
char chunk[17];
size_t got;
int index = 0;
while ((got = bj_read_stream(file, chunk, 16)) > 0) {
chunk[got] = '\0';
bj_info("chunk %d: \"%s\"", index++, chunk);
}
bj_info("Stopped with %s", bj_stream_status(file) == BJ_STREAM_STATUS_END ? "the end of the file" : "an error");
return remove(PATH) == 0 ? 0 : 1;
}
struct bj_stream bj_stream
Definition api.h:374
struct bj_error bj_error
Definition api.h:348
uint32_t bj_bool
Boolean type used throughout the Banjo API.
Definition api.h:264
#define BJ_FALSE
Boolean false value (0).
Definition api.h:273
const char * bj_error_message(const struct bj_error *error)
Gets the error message from an error object.
void bj_clear_error(struct bj_error **error)
Frees an error and sets the pointer to NULL.
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
#define bj_err(...)
Log a message using the BJ_LOG_ERROR level.
Definition log.h:169
size_t bj_stream_length(struct bj_stream *stream)
Return the total size of the stream, in bytes.
void bj_destroy_stream(struct bj_stream *stream)
Destroy a stream and release its memory.
struct bj_stream * bj_create_stream_from_path(struct bj_str path, uint32_t flags, struct bj_error **error)
Create a stream that reads, writes or creates a file.
size_t bj_write_stream(struct bj_stream *stream, const void *data, size_t count)
Writes bytes at the cursor, over those already there.
bj_bool bj_stream_is_mapped(const struct bj_stream *stream)
Whether the stream reads a file mapped into memory.
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_CREATE
A missing file is created.
Definition stream.h:134
@ BJ_STREAM_WRITE
The stream writes.
Definition stream.h:131
@ BJ_STREAM_READ
The stream reads.
Definition stream.h:130
@ BJ_STREAM_TRUNCATE
The file is emptied when opened.
Definition stream.h:133
@ BJ_STREAM_APPEND
Every write goes to the end of the file.
Definition stream.h:132
@ BJ_STREAM_STATUS_END
The data ran out, or a fixed-size stream is full.
Definition stream.h:152
#define BJ_STR(literal)
Create a view of a string literal.
Definition string.h:75
Logging utility functions.
Portable main() replacement with platform-aware entry shim.
Header file for struct bj_stream struct and related functions.
static bj_bool write_text(const char *text, uint32_t flags)
Definition stream_file.c:30
#define PATH
Definition stream_file.c:28
UTF-8 string views and owning strings.
int main(void)