about.md- allocator.h.md
- array_list.h.md
- buffer.h.md
- collection.h.md
- collections.md
- compare.h.md
- features.md
- hash_key.h.md
- hash_map.h.md
- install.md
- iterator.h.md
- json.h.md
- kv_list.h.md
- license.md
- linked_list.h.md
- list.h.md
- map.h.md
- memory.md
- mempool.h.md
- parsers.md
- printf.h.md
- properties.h.md
- streams.h.md
- string.h.md
- strings.md
- test.h.md
- tree.h.md
- utils.md
# 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()`).
> 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 _successfully_ 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.
>{style="note"}
> 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>