@deffn Typedef stream_gpointer
@fnindex stream_gpointer

A portable generic pointer which works with K&R compilers too.
We use a different generic pointer typedef to the rest of snprintfv,
to make it easy for anyone who wants to extract the stream files
from this dist' and use them without pulling in all the compat.h
generation code and associated dependencies.

@end deffn

@deffn Typedef STREAM
@fnindex STREAM

Data type used to pass details of streams between functions,
much like stdio's FILE, but more flexible.  A STREAM can be uni- or
bi-directional depending on how it is initialised.

@end deffn

@deftypefn Typedef int sstream_put_function sstream_put_function(int c@var{ch}, STREAM *s@var{stream})
@fnindex stream_put_function


Type of the function to put a character in a writeable stream.


The function should return the character written to the
stream, cast to an int if it was written successfully, or
else EOF, if the write failed.

@end deftypefn

@deftypefn Typedef int sstream_get_function sstream_get_function(STREAM *s@var{stream})
@fnindex stream_get_function


Type of the function to get a character from a readable stream.


The function should return the character read from the
stream, cast to an int if it was read successfully, or
else EOF, if the read failed.

@end deftypefn

@deftypefn Typedef int stream_finalize_function stream_finalize_function(stream_gpointer *d@var{dets})
@fnindex stream_finalize_function


Type of the function to clean up any user supplied stream
details (such as closing file descriptors) before recycling
the containing structure.


Should eturns 0 if @var{dets} is successfully finalized, or else -1.

@end deftypefn

@deftypefn Function STREAM* stream_new (stream_gpointer d@var{dets}, unsigned long l@var{limit}, stream_gget_function *g@var{get_func}, stream_pput_function *p@var{put_func}, stream_ffinalize_function *f@var{finalize_func})
@fnindex stream_new


Allocate and initialize a new STREAM data type.


The address of the newly allocated and initialised stream is returned.

@end deftypefn

@deftypefn Function void sstream_delete (STREAM *s@var{stream})
@fnindex stream_delete


The finalization function specified when @var{stream} was created (if any)
is called, and then the memory associated with @var{stream} is recycled.
It is the responsibility of the finalization function to recycle, or
otherwise manage, any memory associated with the user supplied %dets.

@end deftypefn

@deftypefn Function void sstream_init (STREAM *s@var{stream}, sstream_gpointer d@var{dets}, unsigned long l@var{limit}, sstream_gget_function *g@var{get_func}, sstream_pput_function *p@var{put_func})
@fnindex stream_init


Initialize @var{stream} with the data contained in the arguments to this
function.

@end deftypefn

@deftypefn Function int sstream_put (int c@var{ch}, STREAM *s@var{stream})
@fnindex stream_put


This function will @var{ch} in @var{stream} if that stream's output limit will
not be exceeded.


If @var{stream} is full, or any other error occurs, that error code is
returned unchanged.  This is of course dependant on what the handler
function uses to indicate an error.  Otherwise, 1 (the number of
characters emitted!) is returned.

@end deftypefn

@deftypefn Function int sstream_get (STREAM *s@var{stream})
@fnindex stream_get


This function will try to read a single character from @var{stream}.


If an error occurs or the end of @var{stream} is reached, -1 is returned.
Under normal circumstances the value if the character read (cast to
an int) is returned.

@end deftypefn

