Standard stream handling utilities. More...

#include "platform.h"
#include <stdbool.h>
#include <stdio.h>
#include <sys/types.h>
#include <assert.h>

Include dependency graph for stdstreams.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	string_stream
	String stream internal state structure. More...

Typedefs
typedef struct stream *	stream_t
	Opaque stream handle.

Functions
bool	readline (const char prompt, char buffer, size_t buffer_len)
	Read a line from stdin, optionally printing a prompt first.

int	getpassword (const char prompt, char buffer, size_t buffer_len)
	Read a password from the terminal with echo disabled.

stream_t	create_file_stream (FILE *fp)
	Wrap an existing FILE* in a standardized stream context.

stream_t	create_string_stream (size_t initial_capacity)
	Allocate a new in-memory string stream.

void	stream_destroy (stream_t stream)
	Destroy a stream and release all connected resources.

int	stream_seek (stream_t stream, long offset, int whence)
	Seek within a stream exactly matching POSIX fseek(3) semantics.

size_t	file_stream_read (stream_t s, void *restrict ptr, size_t size, size_t count)
	Read up to `count` objects of `size` bytes from a file stream into `ptr`, rewinding to the beginning first.

int	string_stream_write (stream_t stream, const char *str)
	Append the NUL-terminated string `str` to `stream`.

int	string_stream_write_len (stream_t stream, const char *str, size_t n)
	Append the NUL-terminated string `str` to `stream`. This is faster than string_stream_write when the length of `str` is already known. The internal position cursor is explicitly not advanced (append semantics). Safe to execute irrespective of current seek states.

const char *	string_stream_data (stream_t stream)
	Fetch a read-only view of the underlying strictly NUL-terminated string data.

ssize_t	read_until (stream_t stream, int delim, char *buffer, size_t buffer_size)
	Read from `stream` into `buffer` until `delim` is found.

unsigned long	string_stream_copy_fast (stream_t dst, stream_t src)
	Direct memory-bound string to string copy without generic dispatch.

unsigned long	io_copy (stream_t writer, stream_t reader)
	Copy contents universally from `reader` into `writer`.

unsigned long	io_copy_n (stream_t writer, stream_t reader, size_t n)
	Copy tightly capped chunk up to `n` bytes.

Detailed Description

Standard stream handling utilities.

Two-layer API: Layer 1 — type-specialized fast paths (string_stream_copy_fast, etc.) Layer 2 — generic fallback (io_copy, io_copy_n, read_until)

Error contract (unified, POSIX-style):

‍0 → bytes read / written 0 → EOF -1 → error

All allocations have been strictly optimized to prevent fragmentation and excessive malloc overhead. String streams reliably guarantee correct trailing NUL-terminators for unsafe downstream processing.

Definition in file stdstreams.h.

Typedef Documentation

◆ stream_t

typedef struct stream* stream_t

Opaque stream handle.

Wraps FILE* and in-memory string buffers behind a uniform interface. Callers must never dereference the pointer directly.

Definition at line 81 of file stdstreams.h.

Function Documentation

◆ create_file_stream()

stream_t create_file_stream ( FILE * fp )

Wrap an existing FILE* in a standardized stream context.

Ownership of fp is conditionally taken only when it is not one of the standards (stdin / stdout / stderr).

Parameters

fp	Target file pointer.

Returns: Stream handle, or NULL on allocation failure.

Definition at line 145 of file stdstreams.c.

References create_file_stream().

Referenced by create_file_stream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create_string_stream()

stream_t create_string_stream ( size_t initial_capacity )

Allocate a new in-memory string stream.

Combines allocations for caching efficiency. Automatically manages growth sizes exponentially to skip redundant allocations.

Parameters

initial_capacity Desired starting size (can be 0).

Returns: Stream handle, or NULL on allocation failure.

Definition at line 307 of file stdstreams.c.

References string_stream::capacity, create_string_stream(), string_stream::data, string_stream::pos, and string_stream::size.

Referenced by create_string_stream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ file_stream_read()

size_t file_stream_read	(	stream_t	s,
		void *restrict	ptr,
		size_t	size,
		size_t	count
	)

Read up to count objects of size bytes from a file stream into ptr, rewinding to the beginning first.

Parameters

s	Source file stream.
ptr	Destination buffer pointer.
size	Size in bytes of an individual unit block.
count	Amount of items to fetch.

Returns: Number of objects read, 0 on EOF, (size_t)-1 on error.

Definition at line 161 of file stdstreams.c.

References file_stream_read().

Referenced by file_stream_read().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getpassword()

int getpassword	(	const char *	prompt,
		char *	buffer,
		size_t	buffer_len
	)

Read a password from the terminal with echo disabled.

Uses termios on POSIX systems, and Console API on Win32.

Parameters

prompt	Optional prompt string (can be NULL).
buffer	Destination buffer.
buffer_len	Total size of the buffer.

Returns: The number of characters stored in buffer, or -1 on error.

Definition at line 53 of file stdstreams.c.

References getpassword(), and readline().

Referenced by getpassword().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ io_copy()

unsigned long io_copy	(	stream_t	writer,
		stream_t	reader
	)

Copy contents universally from reader into writer.

Uses optimal vtable-bypassing fast-paths seamlessly if types match.

Parameters

writer	Destination generalized stream.
reader	Target generalized source stream.

Returns: Total bytes written, or (unsigned long)-1 on error.

Definition at line 427 of file stdstreams.c.

References io_copy(), and string_stream_copy_fast().

Referenced by io_copy().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ io_copy_n()

unsigned long io_copy_n	(	stream_t	writer,
		stream_t	reader,
		size_t	n
	)

Copy tightly capped chunk up to n bytes.

Parameters

writer	Destination generalized stream.
reader	Target generalized source stream.
n	Maximum ceiling of bytes to shift.

Returns: Total bytes written (≤ n), or (unsigned long)-1 on error.

Definition at line 451 of file stdstreams.c.

References io_copy_n().

Referenced by io_copy_n().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ read_until()

ssize_t read_until	(	stream_t	stream,
		int	delim,
		char *	buffer,
		size_t	buffer_size
	)

Read from stream into buffer until delim is found.

Heavily optimized out internally if the target matches a string stream. The buffer is reliably NUL-terminated. Delimiter is excluded from results.

Parameters

stream	Source stream.
delim	Delimiter character boundary trigger.
buffer	Destination array — continuously NUL-terminated.
buffer_size	Total cap of `buffer`.

Returns: characters stored (≥ 0), or -1 on error / initial EOF.

Definition at line 344 of file stdstreams.c.

References string_stream::data, LIKELY, string_stream::pos, read_until(), and string_stream::size.

Referenced by read_until().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readline()

bool readline	(	const char *	prompt,
		char *	buffer,
		size_t	buffer_len
	)

Read a line from stdin, optionally printing a prompt first.

Strips the trailing newline. Overflow characters are safely drained from the input buffer.

Parameters

prompt	Optional prompt string (can be NULL).
buffer	Destination buffer.
buffer_len	Total size of the buffer.

Returns: true on success, false on EOF / error.

Definition at line 35 of file stdstreams.c.

References readline().

Referenced by getpassword(), and readline().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stream_destroy()

void stream_destroy ( stream_t stream )

Destroy a stream and release all connected resources.

For file streams, the underlying FILE* is safely closed unless it belongs to the standard standard handles (stdin/stdout/stderr).

Parameters

stream Stream to destroy.

Definition at line 503 of file stdstreams.c.

References stream_destroy().

Referenced by stream_destroy().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stream_seek()

int stream_seek	(	stream_t	stream,
		long	offset,
		int	whence
	)

Seek within a stream exactly matching POSIX fseek(3) semantics.

Parameters

stream	Stream handle.
offset	Relative byte offset.
whence	Target relative origin (SEEK_SET, SEEK_CUR, SEEK_END).

Returns: 0 on success, -1 on bounds violation or error.

Definition at line 125 of file stdstreams.c.

References stream_seek().

Referenced by stream_seek().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ string_stream_copy_fast()

unsigned long string_stream_copy_fast	(	stream_t	dst,
		stream_t	src
	)

Direct memory-bound string to string copy without generic dispatch.

Copy all bytes linearly from src string to dst string.

Parameters

dst	Destination string stream.
src	Target source string stream.

Returns: Bytes copied, or (unsigned long)-1 on allocation failure.

Definition at line 394 of file stdstreams.c.

References string_stream::data, string_stream::pos, string_stream::size, and string_stream_copy_fast().

Referenced by io_copy(), and string_stream_copy_fast().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ string_stream_data()

const char * string_stream_data ( stream_t stream )

Fetch a read-only view of the underlying strictly NUL-terminated string data.

Parameters

stream String stream handle.

Returns: Direct buffer pointer or NULL if type invalid.

Definition at line 302 of file stdstreams.c.

References string_stream_data().

Referenced by string_stream_data().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ string_stream_write()

int string_stream_write	(	stream_t	stream,
		const char *	str
	)

Append the NUL-terminated string str to stream.

The internal position cursor is explicitly not advanced (append semantics). Safe to execute irrespective of current seek states.

Parameters

stream	Target string stream.
str	NUL-terminated string literal.

Returns: The number of bytes appended, or -1 on allocation failure.

Definition at line 271 of file stdstreams.c.

References string_stream::data, string_stream::size, and string_stream_write().

Referenced by string_stream_write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ string_stream_write_len()

int string_stream_write_len	(	stream_t	stream,
		const char *	str,
		size_t	n
	)

Append the NUL-terminated string str to stream. This is faster than string_stream_write when the length of str is already known. The internal position cursor is explicitly not advanced (append semantics). Safe to execute irrespective of current seek states.

Parameters

stream	Target string stream.
str	NUL-terminated string literal.
n	Maximum number of bytes to append from `str` (excluding NUL).

Returns: The number of bytes appended, or -1 on allocation failure.

Definition at line 287 of file stdstreams.c.

References string_stream::data, string_stream::size, and string_stream_write_len().

Referenced by string_stream_write_len().

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ stream_t

Function Documentation

◆ create_file_stream()

◆ create_string_stream()

◆ file_stream_read()

◆ getpassword()

◆ io_copy()

◆ io_copy_n()

◆ read_until()

◆ readline()

◆ stream_destroy()

◆ stream_seek()

◆ string_stream_copy_fast()

◆ string_stream_data()

◆ string_stream_write()

◆ string_stream_write_len()