Streams and Capabilities

Data Structures
struct	ConCaps

Macros
#define	withConLock(con)   blkWrap (conLock(con), conUnlock(con))

Typedefs
typedef struct ConStream	ConStream
typedef enum ConColorDepth	ConColorDepth
	Color depth a stream is able to render.
typedef struct ConCaps	ConCaps

Enumerations
enum	ConColorDepth { CON_ColorNone = 0 , CON_Color16 , CON_Color256 , CON_ColorTrue }
	Color depth a stream is able to render. More...

Functions
ConStream *	conOut (void)
ConStream *	conErr (void)
ConStream *	conIn (void)
void	conShutdown (void)
ConStream *	conCreateMem (const ConCaps *caps)
void	conMemGet (ConStream *con, string *out)
void	conDestroy (ConStream **con)
void	conGetCaps (ConStream *con, ConCaps *out)
uint16	conWidth (ConStream *con)
	Current terminal width in columns, re-queried on every call. 0 if unknown or not a tty.
uint16	conHeight (ConStream *con)
	Current terminal height in rows, re-queried on every call. 0 if unknown or not a tty.
void	conLock (ConStream *con)
void	conUnlock (ConStream *con)

Detailed Description

Macro Definition Documentation

withConLock

#define withConLock

(

con

)

blkWrap (conLock(con), conUnlock(con))

void withConLock(ConStream *con) { ... }

Executes a block with the stream locked for its duration, unlocking automatically on every exit path (including early return or break).

Example:

withConLock(con) {
    conPuts(con, _SL("fatal: "));
    conPuts(con, msg);
    conNL(con);
}

Parameters

con	Stream to lock for the duration of the block

Definition at line 145 of file console.h.

Typedef Documentation

ConCaps

typedef struct ConCaps ConCaps

Capabilities of a console stream, detected once at stream initialization from environment variables and a platform probe (never from a terminfo/termcap database).

ConStream

typedef struct ConStream ConStream

Opaque handle to a console stream. Obtain via conOut(), conErr(), conIn(), or conCreateMem(). Never access members directly.

Definition at line 20 of file console.h.

Enumeration Type Documentation

ConColorDepth

enum ConColorDepth

Color depth a stream is able to render.

Enumerator
CON_ColorNone	No color support; styling is a no-op.
CON_Color16	Standard + bright ANSI 16-color palette.
CON_Color256	256-color palette (6x6x6 cube + grayscale ramp + 16 base)
CON_ColorTrue	24-bit RGB

Definition at line 23 of file console.h.

Function Documentation

conCreateMem()

ConStream * conCreateMem

(

const ConCaps *

caps

)

ConStream* conCreateMem(const ConCaps *caps)

Creates a memory-backed console stream for testing.

Writes are captured into an internal string instead of reaching any real terminal, and nothing this module does ever logs, so it is safe to use inside log-destination tests as well. Behaves exactly like a real stream to every other function in this module.

Parameters

caps	Capabilities to report for this stream (copied)

Returns

A new memory-backed stream

Example:

ConCaps caps = { .istty = true, .color = CON_Color256, .width = 80 };
ConStream *con = conCreateMem(&caps);
conPuts(con, _SL("hello"));
 
string out = 0;
conMemGet(con, &out);   // out == "hello"
strDestroy(&out);
conDestroy(&con);

conDestroy()

void conDestroy

(

ConStream **

con

)

Destroys a memory-backed stream created with conCreateMem(). Never call this on conOut()/conErr()/conIn() – they are process singletons and are never destroyed.

Parameters

con	Pointer to the stream handle; set to NULL on return

conErr()

ConStream * conErr

(

void

)

Returns the process-wide standard error stream, creating it on first call.

Always unbuffered – every write reaches the underlying stream immediately, so crash-adjacent diagnostics are never lost in a buffer.

Returns

The standard error stream

conGetCaps()

void conGetCaps	(	ConStream *	con,
		ConCaps *	out
	)

Retrieves the current capabilities of a stream. Terminal size is re-queried; everything else was detected once at stream initialization.

Parameters

con	Stream to query
out	Receives a copy of the stream's capabilities

conIn()

ConStream * conIn

(

void

)

Returns the process-wide standard input stream, creating it on first call.

Returns

The standard input stream

conLock()

void conLock

(

ConStream *

con

)

Locks a stream for the calling thread.

Every public function in this module already locks internally, so explicit locking is only needed to group several calls into one sequence atomic with respect to other threads. Reentrant from the owning thread via an internal depth counter – nested conLock()/conUnlock() pairs on the same thread are supported and cheap – but never share a lock across threads without a matching unlock.

Parameters

con	Stream to lock

conMemGet()

void conMemGet	(	ConStream *	con,
		string *	out
	)

Copies everything written to a memory-backed stream so far into *out, replacing any value already there. Does not clear the stream's internal capture buffer.

Parameters

con	A stream created with conCreateMem()
out	Receives a copy of the captured output

conOut()

ConStream * conOut

(

void

)

Returns the process-wide standard output stream, creating it on first call.

The returned pointer is a permanent singleton; it is never destroyed and must not be passed to conDestroy(). Safe to call from any thread at any time.

Returns

The standard output stream

conShutdown()

void conShutdown

(

void

)

Restores terminal state changed by this module and flushes all singleton streams that have been created. Safe to call more than once. Does not free the singletons; they remain usable afterward.

conUnlock()

void conUnlock

(

ConStream *

con

)

Unlocks a stream previously locked with conLock(). Must be called once per matching conLock() call, from the same thread.

Parameters

con	Stream to unlock