Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Data Stream

Data Structures

struct  bj_stream_callbacks

Macros

#define bj_stream_read_t(stream, type, buffer)
#define bj_stream_skip_t(stream, type)

Typedefs

typedef enum bj_seek_origin bj_seek_origin
typedef enum bj_stream_flag bj_stream_flag
typedef size_t(* bj_stream_read_fn) (void *buffer, size_t count, void *user_data, enum bj_stream_status *status)
typedef size_t(* bj_stream_write_fn) (const void *data, size_t count, void *user_data, enum bj_stream_status *status)
typedef bj_bool(* bj_stream_seek_fn) (size_t position, void *user_data)
typedef size_t(* bj_stream_size_fn) (void *user_data)
typedef bj_bool(* bj_stream_flush_fn) (void *user_data)
typedef void(* bj_stream_close_fn) (void *user_data)

Enumerations

enum  bj_seek_origin { BJ_SEEK_BEGIN = 0x00 , BJ_SEEK_CURRENT = 0x01 , BJ_SEEK_END = 0x02 }
enum  bj_stream_flag {
  BJ_STREAM_READ = 0x01 , BJ_STREAM_WRITE = 0x02 , BJ_STREAM_APPEND = 0x04 , BJ_STREAM_TRUNCATE = 0x08 ,
  BJ_STREAM_CREATE = 0x10 , BJ_STREAM_EXCLUSIVE = 0x20 , BJ_STREAM_READ_WRITE = BJ_STREAM_READ | BJ_STREAM_WRITE
}
enum  bj_stream_status {
  BJ_STREAM_STATUS_OK = 0 , BJ_STREAM_STATUS_END = 1 , BJ_STREAM_STATUS_NOT_READY = 2 , BJ_STREAM_STATUS_ERROR = 3 ,
  BJ_STREAM_STATUS_READ_ONLY = 4 , BJ_STREAM_STATUS_WRITE_ONLY = 5 , BJ_STREAM_STATUS_LOCKED = 6
}

Functions

struct bj_stream * bj_create_stream (void)
struct bj_stream * bj_allocate_stream (void)
struct bj_stream * bj_create_stream_from_read_memory (const void *data, size_t length)
struct bj_stream * bj_open_stream_read (const void *data, size_t length)
struct bj_stream * bj_create_stream_from_memory (void *data, size_t length, uint32_t flags)
struct bj_stream * bj_create_stream_from_path (struct bj_str path, uint32_t flags, struct bj_error **error)
struct bj_stream * bj_open_stream_file (const char *path, struct bj_error **error)
struct bj_stream * bj_create_stream_from_callbacks (const struct bj_stream_callbacks *callbacks, uint32_t flags, void *user_data, struct bj_error **error)
struct bj_stream * bj_create_stream_span (struct bj_stream *parent, size_t offset, size_t length)
void bj_destroy_stream (struct bj_stream *stream)
void bj_close_stream (struct bj_stream *stream)
size_t bj_read_stream (struct bj_stream *stream, void *dest, size_t count)
size_t bj_write_stream (struct bj_stream *stream, const void *data, size_t count)
bj_bool bj_flush_stream (struct bj_stream *stream)
size_t bj_stream_length (struct bj_stream *stream)
size_t bj_get_stream_length (struct bj_stream *stream)
size_t bj_seek_stream (struct bj_stream *stream, ptrdiff_t position, enum bj_seek_origin from)
size_t bj_stream_position (struct bj_stream *stream)
size_t bj_tell_stream (struct bj_stream *stream)
const void * bj_stream_peek (struct bj_stream *stream, size_t offset, size_t length)
enum bj_stream_status bj_stream_status (const struct bj_stream *stream)
void bj_clear_stream_status (struct bj_stream *stream)
uint32_t bj_stream_flags (const struct bj_stream *stream)
bj_bool bj_stream_has_flag (const struct bj_stream *stream, enum bj_stream_flag flag)
bj_bool bj_stream_is_seekable (const struct bj_stream *stream)
bj_bool bj_stream_is_mapped (const struct bj_stream *stream)

Byte-order reads and writes

Each reader takes the bytes of one integer at the cursor and decodes them in the order its name gives, _le for little-endian and _be for big-endian, whatever the order of the computer.

Signed integers are in two's complement. It gives BJ_TRUE when all the bytes were there. Else BJ_FALSE, with the destination left as it was, the bytes that were left consumed, and the reason in bj_stream_status. A 0 destination skips the integer.

Each writer stores one integer at the cursor in the order its name gives, and gives BJ_TRUE when all its bytes went through.

A 0 stream gives BJ_FALSE.

bj_bool bj_read_stream_u8 (struct bj_stream *stream, uint8_t *value)
bj_bool bj_read_stream_i8 (struct bj_stream *stream, int8_t *value)
bj_bool bj_read_stream_u16_le (struct bj_stream *stream, uint16_t *value)
bj_bool bj_read_stream_u16_be (struct bj_stream *stream, uint16_t *value)
bj_bool bj_read_stream_i16_le (struct bj_stream *stream, int16_t *value)
bj_bool bj_read_stream_i16_be (struct bj_stream *stream, int16_t *value)
bj_bool bj_read_stream_u32_le (struct bj_stream *stream, uint32_t *value)
bj_bool bj_read_stream_u32_be (struct bj_stream *stream, uint32_t *value)
bj_bool bj_read_stream_i32_le (struct bj_stream *stream, int32_t *value)
bj_bool bj_read_stream_i32_be (struct bj_stream *stream, int32_t *value)
bj_bool bj_read_stream_u64_le (struct bj_stream *stream, uint64_t *value)
bj_bool bj_read_stream_u64_be (struct bj_stream *stream, uint64_t *value)
bj_bool bj_read_stream_i64_le (struct bj_stream *stream, int64_t *value)
bj_bool bj_read_stream_i64_be (struct bj_stream *stream, int64_t *value)
bj_bool bj_write_stream_u8 (struct bj_stream *stream, uint8_t value)
bj_bool bj_write_stream_i8 (struct bj_stream *stream, int8_t value)
bj_bool bj_write_stream_u16_le (struct bj_stream *stream, uint16_t value)
bj_bool bj_write_stream_u16_be (struct bj_stream *stream, uint16_t value)
bj_bool bj_write_stream_i16_le (struct bj_stream *stream, int16_t value)
bj_bool bj_write_stream_i16_be (struct bj_stream *stream, int16_t value)
bj_bool bj_write_stream_u32_le (struct bj_stream *stream, uint32_t value)
bj_bool bj_write_stream_u32_be (struct bj_stream *stream, uint32_t value)
bj_bool bj_write_stream_i32_le (struct bj_stream *stream, int32_t value)
bj_bool bj_write_stream_i32_be (struct bj_stream *stream, int32_t value)
bj_bool bj_write_stream_u64_le (struct bj_stream *stream, uint64_t value)
bj_bool bj_write_stream_u64_be (struct bj_stream *stream, uint64_t value)
bj_bool bj_write_stream_i64_le (struct bj_stream *stream, int64_t value)
bj_bool bj_write_stream_i64_be (struct bj_stream *stream, int64_t value)

Detailed Description

Read and write bytes through one API, whatever holds them: memory, a file, a network connection, the caller's own functions, or a range of another stream.

A stream is a moving cursor over a sequence of bytes. The caller iteratively asks for N bytes, moving the cursor ahead until we reach the end. The API is similar to the standard C FILE* handle, with the exception that a stream initialisation abstract away several possible sources of data: file, network, memory buffer or custom sources. This abstraction allows any user code to operate on streamed data without any knowledge about the originating source of the data.

Create a stream

Constructor Bytes
bj_create_stream memory the stream owns and grows
bj_create_stream_from_read_memory a caller buffer, read-only, not copied
bj_create_stream_from_memory a caller buffer, in place, never grows
bj_create_stream_from_path a file, read and written on demand
bj_create_stream_from_callbacks the program's functions (archives, codecs…)
bj_create_stream_span a range of another stream, a span
bj_create_stream_from_tcp a TCP connection, see net.h

Whatever the source, release the stream with bj_destroy_stream.

Stream Flags

A stream reads when its flags hold BJ_STREAM_READ and writes when they hold BJ_STREAM_WRITE. Both together are BJ_STREAM_READ_WRITE. Files take four more, which combine as the modes of fopen do:

fopen Flags
"r" BJ_STREAM_READ
"r+" BJ_STREAM_READ_WRITE
"w" BJ_STREAM_WRITE \| BJ_STREAM_CREATE \| BJ_STREAM_TRUNCATE
"a" BJ_STREAM_WRITE \| BJ_STREAM_CREATE \| BJ_STREAM_APPEND
"wx" BJ_STREAM_WRITE \| BJ_STREAM_CREATE \| BJ_STREAM_EXCLUSIVE

bj_stream_flags and bj_stream_has_flag give the flags back.

Capabilities

Whether a stream can move its cursor, and whether a file is mapped into memory, depends on the source. The functions bj_stream_is_seekable and bj_stream_is_mapped query for these capabilities. For example, a TCP connection cannot seek.

Read and Write Bytes

uint8_t header[14];
bj_read_stream(stream, header, sizeof header);
uint32_t width;
bj_read_stream_u32_le(stream, &width); // Read unsigned 32 as little endian
bj_write_stream_u16_be(out, 0x0001); // Write unsigned 16 as big endian
bj_bool bj_write_stream_u16_be(struct bj_stream *stream, uint16_t value)
Writes a big-endian uint16_t.
bj_bool bj_read_stream_u32_le(struct bj_stream *stream, uint32_t *value)
Reads a little-endian uint32_t.
size_t bj_read_stream(struct bj_stream *stream, void *dest, size_t count)
Reads data from the stream into a destination buffer.

A read or a write returns how many bytes it moved. The byte-order functions (such as bj_read_stream_u32_le) return BJ_TRUE only when the whole integer went through, whatever the byte order of the computer running the program.

Stream Status

When a count falls short, bj_stream_status says why:

Random Access, Spans and Peeking

bj_seek_stream moves the cursor. bj_stream_position tells where it currently is. bj_stream_length tells the total size of the data.

Seeking past either end doesn't fail. It clamps to the boundary.

bj_create_stream_span turns a range of an existing stream into a new, independent stream. This span cannot reach data outside of the given range.

Threads

A stream belongs to one thread at a time.


Data Structure Documentation

◆ bj_stream_callbacks

struct bj_stream_callbacks

The functions of a source the program supplies.

Each function receives the user_data given to bj_create_stream_from_callbacks.

It is possible to set 0 to some of the function pointers:

  • without read, the stream cannot read, and without write, it cannot write.
  • with both seek and size, the stream can seek. Otherwise it cannot, and its length is what size gives, or 0 without it.
  • without flush, flushing succeeds at once.
  • without close, destroying the stream only frees the stream object.

The stream copies this table, so it can live on the stack, or be one static const table shared by every stream of the program.

Examples
stream_custom.c.

Definition at line 257 of file stream.h.

Data Fields
bj_stream_close_fn close Releases the source, or 0.
bj_stream_flush_fn flush Flushes, or 0.
bj_stream_read_fn read Reads bytes, or 0.
bj_stream_seek_fn seek Moves the source's cursor, or 0.
bj_stream_size_fn size Gives the size, or 0.
bj_stream_write_fn write Writes bytes, or 0.

Macro Definition Documentation

◆ bj_stream_read_t

#define bj_stream_read_t ( stream,
type,
buffer )
Value:
bj_read_stream(stream, buffer, sizeof(type))

Reads data of a specified type from the stream into a buffer.

The value is in the byte order of the computer running the program. For a file format, prefer the byte-order readers such as bj_read_stream_u32_le.

Parameters
streamPointer to the stream instance.
typeData type to read.
bufferPointer to the buffer to store the read data.
Deprecated
A plain bj_read_stream with sizeof reads the same bytes. Removed in 2.0.

Definition at line 712 of file stream.h.

◆ bj_stream_skip_t

#define bj_stream_skip_t ( stream,
type )
Value:
bj_read_stream(stream, 0, sizeof(type))

Skips bytes of a specified type from the stream.

Parameters
streamPointer to the stream instance.
typeData type to skip.

Definition at line 720 of file stream.h.

Typedef Documentation

◆ bj_seek_origin

Definition at line 120 of file stream.h.

◆ bj_stream_close_fn

typedef void(* bj_stream_close_fn) (void *user_data)

Releases the source, once, when the stream is destroyed.

Parameters
user_dataThe pointer given to bj_create_stream_from_callbacks.

Definition at line 235 of file stream.h.

◆ bj_stream_flag

Definition at line 139 of file stream.h.

◆ bj_stream_flush_fn

typedef bj_bool(* bj_stream_flush_fn) (void *user_data)

Pushes the bytes the source holds back to where they go.

Parameters
user_dataThe pointer given to bj_create_stream_from_callbacks.
Returns
BJ_TRUE on success.

Definition at line 226 of file stream.h.

◆ bj_stream_read_fn

typedef size_t(* bj_stream_read_fn) (void *buffer, size_t count, void *user_data, enum bj_stream_status *status)

Moves up to count bytes from the source into buffer.

Parameters
bufferWhere to put the bytes, never 0.
countHow many bytes the stream wants, never 0.
user_dataThe pointer given to bj_create_stream_from_callbacks.
statusSet to BJ_STREAM_STATUS_OK on entry. Set it to say why fewer bytes came, or leave it to mean the end.
Returns
How many bytes were moved, from 0 to count. The stream calls again until it has count, so returning fewer is fine.

Definition at line 172 of file stream.h.

◆ bj_stream_seek_fn

typedef bj_bool(* bj_stream_seek_fn) (size_t position, void *user_data)

Moves the source's cursor to an absolute position.

The stream keeps its own cursor and calls this only when the source must move before a transfer.

Parameters
positionWhere the source must stand.
user_dataThe pointer given to bj_create_stream_from_callbacks.
Returns
BJ_TRUE when the source now stands at position.

Definition at line 206 of file stream.h.

◆ bj_stream_size_fn

typedef size_t(* bj_stream_size_fn) (void *user_data)

Gives the current size of the source, in bytes.

Parameters
user_dataThe pointer given to bj_create_stream_from_callbacks.

Definition at line 216 of file stream.h.

◆ bj_stream_write_fn

typedef size_t(* bj_stream_write_fn) (const void *data, size_t count, void *user_data, enum bj_stream_status *status)

Moves up to count bytes from data into the source.

Parameters
dataThe bytes to write, never 0.
countHow many bytes to write, never 0.
user_dataThe pointer given to bj_create_stream_from_callbacks.
statusSet to BJ_STREAM_STATUS_OK on entry. Set it to say why fewer bytes went, or leave it to mean an error.
Returns
How many bytes were moved, from 0 to count.

Definition at line 189 of file stream.h.

Enumeration Type Documentation

◆ bj_seek_origin

Position in a bj_stream to use for origin.

Enumerator
BJ_SEEK_BEGIN 

The beginning of the stream.

BJ_SEEK_CURRENT 

The current position of the stream.

BJ_SEEK_END 

The end of the stream.

Definition at line 114 of file stream.h.

◆ bj_stream_flag

What a stream is opened for, combined with |.

BJ_STREAM_READ and BJ_STREAM_WRITE apply to every source. The four others only mean something to bj_create_stream_from_path.

Enumerator
BJ_STREAM_READ 

The stream reads.

BJ_STREAM_WRITE 

The stream writes.

BJ_STREAM_APPEND 

Every write goes to the end of the file.

Needs WRITE.

BJ_STREAM_TRUNCATE 

The file is emptied when opened.

Needs WRITE.

BJ_STREAM_CREATE 

A missing file is created.

Needs WRITE.

BJ_STREAM_EXCLUSIVE 

An existing file is refused.

Needs CREATE.

BJ_STREAM_READ_WRITE 

The stream reads and writes.

Definition at line 129 of file stream.h.

◆ bj_stream_status

Why the last read or write of a stream fell short.

END and NOT_READY are soft: a seek clears them. ERROR, READ_ONLY and WRITE_ONLY are hard: they replace a soft status, and stay until bj_clear_stream_status. The status never stops an operation: it only reports.

Enumerator
BJ_STREAM_STATUS_OK 

Nothing fell short.

BJ_STREAM_STATUS_END 

The data ran out, or a fixed-size stream is full.

BJ_STREAM_STATUS_NOT_READY 

The source could not answer yet, such as a socket whose timeout expired.

BJ_STREAM_STATUS_ERROR 

The source failed.

BJ_STREAM_STATUS_READ_ONLY 

A write on a stream without BJ_STREAM_WRITE.

BJ_STREAM_STATUS_WRITE_ONLY 

A read on a stream without BJ_STREAM_READ.

BJ_STREAM_STATUS_LOCKED 

A transfer on a stream held by a bj_text_wrapper, which is the only reader and writer while it lives.

Examples
stream_custom.c, stream_file.c, stream_memory.c, and stream_spans.c.

Definition at line 150 of file stream.h.

Function Documentation

◆ bj_allocate_stream()

struct bj_stream * bj_allocate_stream ( void )
Deprecated
Renamed to bj_create_stream. Removed in 2.0.

◆ bj_clear_stream_status()

void bj_clear_stream_status ( struct bj_stream * stream)

Sets the status back to BJ_STREAM_STATUS_OK.

Parameters
streamThe stream, or 0, which does nothing.

◆ bj_close_stream()

void bj_close_stream ( struct bj_stream * stream)
Deprecated
Renamed to bj_destroy_stream. Removed in 2.0.

◆ bj_create_stream()

struct bj_stream * bj_create_stream ( void )

Create an empty stream in memory, which reads and writes, and grows as it is written.

The stream owns its bytes; bj_stream_peek gives them back.

Returns
A pointer to a new bj_stream, of flags BJ_STREAM_READ_WRITE and length 0, or 0 when memory runs out.

The caller owns the stream and must release it with bj_destroy_stream.

Examples
stream_memory.c, and text_wrapper.c.

Referenced by main(), and main().

◆ bj_create_stream_from_callbacks()

struct bj_stream * bj_create_stream_from_callbacks ( const struct bj_stream_callbacks * callbacks,
uint32_t flags,
void * user_data,
struct bj_error ** error )

Create a stream over a source the program supplies.

static const struct bj_stream_callbacks archive_entry = {
.read = entry_read,
.seek = entry_seek,
.size = entry_size,
.close = entry_close,
};
&archive_entry,
entry,
&error
);
struct bj_stream bj_stream
Definition api.h:374
struct bj_stream * bj_create_stream_from_callbacks(const struct bj_stream_callbacks *callbacks, uint32_t flags, void *user_data, struct bj_error **error)
Create a stream over a source the program supplies.
@ BJ_STREAM_READ
The stream reads.
Definition stream.h:130
The functions of a source the program supplies.
Definition stream.h:257
Parameters
callbacksThe source's functions, copied. 0 gives 0 and leaves error alone.
flagsBJ_STREAM_READ, BJ_STREAM_WRITE or BJ_STREAM_READ_WRITE.
user_dataHanded to every function, unchanged.
errorOptional error location.
Returns
A new stream, or 0 with BJ_ERROR_INVALID_DOMAIN for other flags, BJ_ERROR_INVALID_PARAMETER for READ without read or WRITE without write, or BJ_ERROR_CANNOT_ALLOCATE. On failure, close is not called, and user_data stays the caller's.
Examples
stream_custom.c.

Referenced by main().

◆ bj_create_stream_from_memory()

struct bj_stream * bj_create_stream_from_memory ( void * data,
size_t length,
uint32_t flags )

Create a stream that reads and writes the caller's buffer in place.

The bytes are not copied, and the buffer must outlive the stream. Its length is length from the start, and it never grows: a write that reaches the end stops there, with BJ_STREAM_STATUS_END.

Parameters
dataThe buffer, or 0, which gives 0 unless length is 0.
lengthThe size of the buffer, in bytes.
flagsBJ_STREAM_READ, BJ_STREAM_WRITE or BJ_STREAM_READ_WRITE. Anything else gives 0.
Returns
A new stream, or 0.

◆ bj_create_stream_from_path()

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.

Parameters
pathThe path, in UTF-8.
flagsA combination of bj_stream_flag; see the Flags section.
errorOptional error location.
Returns
A new stream, or 0 on failure.

Instead of being loaded entirely, the file is read and written on demand. It stays open until the stream is destroyed. A non-empty file opened with BJ_STREAM_READ alone is mapped into memory where the platform allows it, so the system pages in only what is read (see bj_stream_is_mapped). On POSIX systems, a mapped file that another program truncates raises SIGBUS when the missing bytes are read.

Flags
BJ_STREAM_READ, BJ_STREAM_WRITE or BJ_STREAM_READ_WRITE, with BJ_STREAM_APPEND, BJ_STREAM_TRUNCATE and BJ_STREAM_CREATE only with WRITE, and BJ_STREAM_EXCLUSIVE only with CREATE. The table at the head of Data Stream maps them to the modes of fopen.
Error Codes
  • BJ_ERROR_INVALID_DOMAIN when provided flags are outside the accepted ones.
  • BJ_ERROR_INVALID_DATA when the path is not UTF-8 or holds a NUL.
  • BJ_ERROR_FILE_NOT_FOUND when the file is missing and flags do not hold BJ_STREAM_CREATE.
  • BJ_ERROR_IO when the system refuses: an existing file with EXCLUSIVE, a directory, a permission, or a file of 4 GiB or more on a 32-bit target.
  • BJ_ERROR_CANNOT_ALLOCATE when memory runs out.
Examples
stream_file.c.

Referenced by main(), and write_text().

◆ bj_create_stream_from_read_memory()

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.

The bytes are not copied: the stream reads from data directly, so the buffer must outlive the stream. The stream cannot write.

Parameters
dataPointer to the data buffer, or 0, which gives 0 unless length is 0.
lengthLength of the data buffer in bytes.
Returns
A pointer to the new bj_stream, of flags BJ_STREAM_READ. Destroy it with bj_destroy_stream.
Examples
stream_custom.c, and stream_spans.c.

Referenced by main().

◆ bj_create_stream_span()

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.

The span checks its range once, here, and from then on cannot read, write, skip or peek outside it. It has its own cursor, at 0, and its own status. It never moves the parent's cursor nor changes its status. It takes the parent's BJ_STREAM_READ and BJ_STREAM_WRITE, except WRITE when the parent appends, and it never grows.

The span borrows parent: destroy every span before its parent.

Parameters
parentThe stream to span, or 0, which gives 0. A parent that cannot seek gives 0 too.
offsetWhere the range starts in the parent.
lengthHow many bytes the range holds.
Returns
A new stream, or 0 when the range does not fit in the parent's length, or when memory runs out.
Examples
stream_spans.c.

Referenced by main().

◆ bj_destroy_stream()

void bj_destroy_stream ( struct bj_stream * stream)

Destroy a stream and release its memory.

A file stream closes its file. A custom source gets its close call.

Parameters
streamThe stream to destroy. 0 is ignored.
See also
bj_create_stream
bj_create_stream_from_read_memory
bj_create_stream_from_memory
bj_create_stream_from_path
bj_create_stream_from_callbacks
bj_create_stream_span
bj_create_stream_from_tcp
Examples
stream_custom.c, stream_file.c, stream_memory.c, stream_spans.c, and text_wrapper.c.

Referenced by main(), main(), and write_text().

◆ bj_flush_stream()

bj_bool bj_flush_stream ( struct bj_stream * stream)

Pushes what the stream wrote to where it goes.

Memory streams and files have nothing held back, and succeed. A custom source gets its flush call.

Parameters
streamThe stream, or 0, which gives BJ_FALSE.
Returns
BJ_TRUE on success. On failure, the status is BJ_STREAM_STATUS_ERROR.

◆ bj_get_stream_length()

size_t bj_get_stream_length ( struct bj_stream * stream)
Deprecated
Renamed to bj_stream_length. Removed in 2.0.

◆ bj_open_stream_file()

struct bj_stream * bj_open_stream_file ( const char * path,
struct bj_error ** error )
Deprecated
Renamed to bj_create_stream_from_path. Removed in 2.0.

◆ bj_open_stream_read()

struct bj_stream * bj_open_stream_read ( const void * data,
size_t length )
Deprecated
Renamed to bj_create_stream_from_read_memory. Removed in 2.0.

◆ bj_read_stream()

size_t bj_read_stream ( struct bj_stream * stream,
void * dest,
size_t count )

Reads data from the stream into a destination buffer.

Parameters
streamPointer to the stream instance, or 0, which reads 0 bytes.
destPointer to the destination buffer, or 0 to skip the bytes, as bj_stream_skip_t does.
countNumber of bytes to read.
Returns
Number of bytes actually read.

The function advances the stream position by the bytes it read. It keeps asking the source until it has count bytes. When it returns fewer, bj_stream_status says why: BJ_STREAM_STATUS_END when the data ran out, BJ_STREAM_STATUS_WRITE_ONLY for a stream without BJ_STREAM_READ, and so on.

Memory Safety

This function does not perform any memory bounds checking. It is the caller's responsibility to ensure dest has enough space to hold count bytes.

Examples
stream_custom.c, stream_file.c, and stream_spans.c.

Referenced by main(), and scrambled_read().

◆ bj_read_stream_i16_be()

bj_bool bj_read_stream_i16_be ( struct bj_stream * stream,
int16_t * value )

Reads a big-endian int16_t.

◆ bj_read_stream_i16_le()

bj_bool bj_read_stream_i16_le ( struct bj_stream * stream,
int16_t * value )

Reads a little-endian int16_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_read_stream_i32_be()

bj_bool bj_read_stream_i32_be ( struct bj_stream * stream,
int32_t * value )

Reads a big-endian int32_t.

◆ bj_read_stream_i32_le()

bj_bool bj_read_stream_i32_le ( struct bj_stream * stream,
int32_t * value )

Reads a little-endian int32_t.

◆ bj_read_stream_i64_be()

bj_bool bj_read_stream_i64_be ( struct bj_stream * stream,
int64_t * value )

Reads a big-endian int64_t.

◆ bj_read_stream_i64_le()

bj_bool bj_read_stream_i64_le ( struct bj_stream * stream,
int64_t * value )

Reads a little-endian int64_t.

◆ bj_read_stream_i8()

bj_bool bj_read_stream_i8 ( struct bj_stream * stream,
int8_t * value )

Reads one signed byte.

◆ bj_read_stream_u16_be()

bj_bool bj_read_stream_u16_be ( struct bj_stream * stream,
uint16_t * value )

Reads a big-endian uint16_t.

Examples
stream_custom.c.

Referenced by main().

◆ bj_read_stream_u16_le()

bj_bool bj_read_stream_u16_le ( struct bj_stream * stream,
uint16_t * value )

Reads a little-endian uint16_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_read_stream_u32_be()

bj_bool bj_read_stream_u32_be ( struct bj_stream * stream,
uint32_t * value )

Reads a big-endian uint32_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_read_stream_u32_le()

bj_bool bj_read_stream_u32_le ( struct bj_stream * stream,
uint32_t * value )

Reads a little-endian uint32_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_read_stream_u64_be()

bj_bool bj_read_stream_u64_be ( struct bj_stream * stream,
uint64_t * value )

Reads a big-endian uint64_t.

◆ bj_read_stream_u64_le()

bj_bool bj_read_stream_u64_le ( struct bj_stream * stream,
uint64_t * value )

Reads a little-endian uint64_t.

◆ bj_read_stream_u8()

bj_bool bj_read_stream_u8 ( struct bj_stream * stream,
uint8_t * value )

Reads one byte.

Examples
stream_memory.c.

Referenced by main().

◆ bj_seek_stream()

size_t bj_seek_stream ( struct bj_stream * stream,
ptrdiff_t position,
enum bj_seek_origin from )

Seeks to a new position in the stream relative to a specified origin.

Parameters
streamPointer to the stream instance, or 0, which gives 0.
positionOffset for the new position.
fromOrigin relative to which the position should be calculated. Another value leaves the cursor where it is.
Returns
The new position within the stream after seeking.

The function clamps the new position to stay within the valid range of the stream, from 0 to the length of the stream, without overflowing, and clears a BJ_STREAM_STATUS_END or BJ_STREAM_STATUS_NOT_READY status. A stream that cannot seek leaves its cursor and status where they are; see bj_stream_is_seekable.

Examples
stream_memory.c, and text_wrapper.c.

Referenced by main(), and main().

◆ bj_stream_flags()

uint32_t bj_stream_flags ( const struct bj_stream * stream)

The flags the stream was created with.

Parameters
streamThe stream, or 0, which gives 0.
Returns
A combination of bj_stream_flag.

◆ bj_stream_has_flag()

bj_bool bj_stream_has_flag ( const struct bj_stream * stream,
enum bj_stream_flag flag )

Whether the stream was created with one flag.

Parameters
streamThe stream, or 0, which gives BJ_FALSE.
flagOne bj_stream_flag; 0 gives BJ_FALSE.
Returns
BJ_TRUE when every bit of flag is set.

◆ bj_stream_is_mapped()

bj_bool bj_stream_is_mapped ( const struct bj_stream * stream)

Whether the stream reads a file mapped into memory.

A non-empty file opened with BJ_STREAM_READ alone is mapped where the platform allows it, and so is a span of such a file.

Parameters
streamThe stream, or 0, which gives BJ_FALSE.
Examples
stream_file.c.

Referenced by main().

◆ bj_stream_is_seekable()

bj_bool bj_stream_is_seekable ( const struct bj_stream * stream)

Whether the stream can move its cursor.

Memory streams, files and spans can. A TCP stream cannot, nor a custom source without both seek and size.

Parameters
streamThe stream, or 0, which gives BJ_FALSE.
Examples
stream_custom.c.

Referenced by main().

◆ bj_stream_length()

size_t bj_stream_length ( struct bj_stream * stream)

Return the total size of the stream, in bytes.

Parameters
streamPointer to the stream instance, or 0, which gives 0.
Returns
The size of the underlying data, in bytes, which grows as a stream that can grow is written. A stream that cannot seek and knows no size, such as a TCP stream, gives 0.
Examples
stream_file.c, stream_memory.c, and text_wrapper.c.

Referenced by main(), and main().

◆ bj_stream_peek()

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.

The bounds are checked here, once: the result is 0 rather than a pointer past the data. Memory streams, mapped files and spans over them point into their own bytes. Other streams copy into a buffer of their own.

Parameters
streamThe stream, or 0, which gives 0.
offsetWhere the bytes start, from the beginning of the stream.
lengthHow many bytes, 0 giving 0.
Returns
A pointer to length bytes, valid until the next call that takes this stream, or its destruction, or 0 when the range is outside the stream, the stream cannot seek, or lacks BJ_STREAM_READ, which also records BJ_STREAM_STATUS_WRITE_ONLY.
Examples
stream_memory.c, and stream_spans.c.

Referenced by main().

◆ bj_stream_position()

size_t bj_stream_position ( struct bj_stream * stream)

Return the current cursor position within the stream.

Parameters
streamPointer to the stream instance, or 0, which gives 0.
Returns
The current position, in bytes from the start. For a stream that cannot seek, the number of bytes it read and wrote.
Examples
stream_spans.c.

Referenced by main().

◆ bj_stream_status()

enum bj_stream_status bj_stream_status ( const struct bj_stream * stream)

Why the last read or write fell short, sticky until cleared.

Parameters
streamThe stream, or 0, which gives BJ_STREAM_STATUS_ERROR.
Returns
The status; bj_stream_status describes the rules.

◆ bj_tell_stream()

size_t bj_tell_stream ( struct bj_stream * stream)
Deprecated
Renamed to bj_stream_position. Removed in 2.0.

◆ bj_write_stream()

size_t bj_write_stream ( struct bj_stream * stream,
const void * data,
size_t count )

Writes bytes at the cursor, over those already there.

The cursor advances past the bytes written. A growable stream, a file and a custom source grow when written past their end. A buffer stream and a span stop at theirs, with BJ_STREAM_STATUS_END. A file opened with BJ_STREAM_APPEND writes at its end, wherever the cursor stood.

Parameters
streamThe stream, or 0, which writes 0 bytes.
dataThe bytes, or 0, which writes 0 bytes.
countHow many bytes to write.
Returns
How many bytes were written. Fewer than count means bj_stream_status says why, such as BJ_STREAM_STATUS_READ_ONLY for a stream without BJ_STREAM_WRITE.
Examples
stream_file.c.

Referenced by write_text().

◆ bj_write_stream_i16_be()

bj_bool bj_write_stream_i16_be ( struct bj_stream * stream,
int16_t value )

Writes a big-endian int16_t.

◆ bj_write_stream_i16_le()

bj_bool bj_write_stream_i16_le ( struct bj_stream * stream,
int16_t value )

Writes a little-endian int16_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_write_stream_i32_be()

bj_bool bj_write_stream_i32_be ( struct bj_stream * stream,
int32_t value )

Writes a big-endian int32_t.

◆ bj_write_stream_i32_le()

bj_bool bj_write_stream_i32_le ( struct bj_stream * stream,
int32_t value )

Writes a little-endian int32_t.

◆ bj_write_stream_i64_be()

bj_bool bj_write_stream_i64_be ( struct bj_stream * stream,
int64_t value )

Writes a big-endian int64_t.

◆ bj_write_stream_i64_le()

bj_bool bj_write_stream_i64_le ( struct bj_stream * stream,
int64_t value )

Writes a little-endian int64_t.

◆ bj_write_stream_i8()

bj_bool bj_write_stream_i8 ( struct bj_stream * stream,
int8_t value )

Writes one signed byte.

◆ bj_write_stream_u16_be()

bj_bool bj_write_stream_u16_be ( struct bj_stream * stream,
uint16_t value )

Writes a big-endian uint16_t.

◆ bj_write_stream_u16_le()

bj_bool bj_write_stream_u16_le ( struct bj_stream * stream,
uint16_t value )

Writes a little-endian uint16_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_write_stream_u32_be()

bj_bool bj_write_stream_u32_be ( struct bj_stream * stream,
uint32_t value )

Writes a big-endian uint32_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_write_stream_u32_le()

bj_bool bj_write_stream_u32_le ( struct bj_stream * stream,
uint32_t value )

Writes a little-endian uint32_t.

Examples
stream_memory.c.

Referenced by main().

◆ bj_write_stream_u64_be()

bj_bool bj_write_stream_u64_be ( struct bj_stream * stream,
uint64_t value )

Writes a big-endian uint64_t.

◆ bj_write_stream_u64_le()

bj_bool bj_write_stream_u64_le ( struct bj_stream * stream,
uint64_t value )

Writes a little-endian uint64_t.

◆ bj_write_stream_u8()

bj_bool bj_write_stream_u8 ( struct bj_stream * stream,
uint8_t value )

Writes one byte.