--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/streams.h.md Tue Feb 11 19:55:32 2025 +0100
@@ -0,0 +1,90 @@
+# Data Streams
+
+Stream copy functions provide a way to copy all - or a limited amount of - data from one stream to another.
+
+Since the read/write functions of a [UCX buffer](buffer.h.md) are fully compatible with stream read/write functions,
+you can, for example, easily transfer data from a file or network stream to a UCX buffer or vice versa.
+
+## Overview
+```C
+#include <cx/streams.h>
+
+size_t cx_stream_copy(
+ void *src, void *dest,
+ cx_read_func rfnc, cx_write_func wfnc
+);
+size_t cx_stream_ncopy(
+ void *src, void *dest,
+ cx_read_func rfnc, cx_write_func wfnc,
+ size_t n
+);
+
+size_t cx_stream_bcopy(
+ void *src, void *dest,
+ cx_read_func rfnc, cx_write_func wfnc,
+ char *buf, size_t bufsize
+);
+size_t cx_stream_bncopy(
+ void *src, void *dest,
+ cx_read_func rfnc, cx_write_func wfnc,
+ char *buf, size_t bufsize,
+ size_t n
+);
+```
+
+## Description
+
+All functions in the stream copy family use the `rfnc` to read data from `src`
+and use the `wfnc` to write the data to `dest`.
+
+The `cx_stream_copy()` function always uses internal stack memory as a temporary buffer for the read bytes.
+The `cx_stream_bcopy()` function uses either a pre-initialized buffer `buf` of length `bufsize`
+or, if `buf` is `NULL`, an internal heap-allocated buffer.
+
+The `cx_stream_ncopy()` function behaves like `cx_stream_copy()` except, that it reads at most `n` bytes
+(and the same is true for `cx_stream_bncopy()` and `cx_stream_bcopy()`).
+
+
+<warning>
+When you are reading from a stream where you cannot track the position, there is the possibility that
+data gets lost when the destination does not accept all the bytes read from the source.
+While the stream copy functions do report how many bytes were <emphasis>successfully</emphasis> copied
+to the destination, this might - in certain cases - not be the exact number of read items.
+
+To mitigate the risk, you should make sure that the destination can always accept all read bytes and
+a possible bottleneck is only introduced by the source.
+</warning>
+
+> The size of the internal _stack_ buffer in `cx_stream_copy()` and `cx_stream_ncopy()` can be
+> set during compilation via the `CX_STREAM_COPY_BUF_SIZE` macro.
+> Similarly, the size for the implicitly allocated _heap_ buffer in can be
+> configured via the `CX_STREAM_BCOPY_BUF_SIZE` macro.
+> Refer to the [build instructions](install.md#compile-time-options) for the details.
+
+## Example
+
+The following example shows, how to read the contents of a file into a buffer:
+```c
+FILE *inputfile = fopen(infilename, "r");
+if (inputfile) {
+ CxBuffer fbuf;
+ cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
+ cx_stream_copy(inputfile, &fbuf,
+ (cx_read_func) fread,
+ cxBufferWriteFunc);
+ fclose(inputfile);
+
+ // ... do something meaningful with the contents ...
+
+ cxBufferDestroy(&fbuf);
+} else {
+ perror("Error opening input file");
+}
+```
+
+
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/streams_8h.html">streams.h</a>
+</category>
+</seealso>
\ No newline at end of file