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
1 # Data Streams
2
3 Stream copy functions provide a way to copy all - or a limited amount of - data from one stream to another.
4
5 Since the read/write functions of a [UCX buffer](buffer.h.md) are fully compatible with stream read/write functions,
6 you can, for example, easily transfer data from a file or network stream to a UCX buffer or vice versa.
7
8 ## Overview
9 ```C
10 #include <cx/streams.h>
11
12 size_t cx_stream_copy(void *src, void *dest,
13 cx_read_func rfnc, cx_write_func wfnc);
14
15 size_t cx_stream_ncopy(void *src, void *dest,
16 cx_read_func rfnc, cx_write_func wfnc, size_t n);
17
18 size_t cx_stream_bcopy(void *src, void *dest,
19 cx_read_func rfnc, cx_write_func wfnc,
20 char *buf, size_t bufsize);
21
22 size_t cx_stream_bncopy(void *src, void *dest,
23 cx_read_func rfnc, cx_write_func wfnc,
24 char *buf, size_t bufsize, size_t n);
25 ```
26
27 ## Description
28
29 All functions in the stream copy family use the `rfnc` to read data from `src`
30 and use the `wfnc` to write the data to `dest`.
31
32 The `cx_stream_copy()` function always uses internal stack memory as a temporary buffer for the read bytes.
33 The `cx_stream_bcopy()` function uses either a pre-initialized buffer `buf` of length `bufsize`
34 or, if `buf` is `NULL`, an internal heap-allocated buffer.
35
36 The `cx_stream_ncopy()` function behaves like `cx_stream_copy()` except, that it reads at most `n` bytes
37 (and the same is true for `cx_stream_bncopy()` and `cx_stream_bcopy()`).
38
39
40 > When you are reading from a stream where you cannot track the position, there is the possibility that
41 > data gets lost when the destination does not accept all the bytes read from the source.
42 > While the stream copy functions do report how many bytes were _successfully_ copied
43 > to the destination, this might - in certain cases - not be the exact number of read items.
44 >
45 > To mitigate the risk, you should make sure that the destination can always accept all read bytes and
46 > a possible bottleneck is only introduced by the source.
47 >{style="note"}
48
49 > The size of the internal _stack_ buffer in `cx_stream_copy()` and `cx_stream_ncopy()` can be
50 > set during compilation via the `CX_STREAM_COPY_BUF_SIZE` macro.
51 > Similarly, the size for the implicitly allocated _heap_ buffer in can be
52 > configured via the `CX_STREAM_BCOPY_BUF_SIZE` macro.
53 > Refer to the [build instructions](install.md#compile-time-options) for the details.
54
55 ## Example
56
57 The following example shows, how to read the contents of a file into a buffer:
58 ```c
59 FILE *inputfile = fopen(infilename, "r");
60 if (inputfile) {
61 CxBuffer fbuf;
62 cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
63 cx_stream_copy(inputfile, &fbuf,
64 (cx_read_func) fread,
65 cxBufferWriteFunc);
66 fclose(inputfile);
67
68 // ... do something meaningful with the contents ...
69
70 cxBufferDestroy(&fbuf);
71 } else {
72 perror("Error opening input file");
73 }
74 ```
75
76
77 <seealso>
78 <category ref="apidoc">
79 <a href="https://ucx.sourceforge.io/api/streams_8h.html">streams.h</a>
80 </category>
81 </seealso>