docs/Writerside/topics/streams.h.md

branch
docs/3.1
changeset 1141
a06a2d27c043
child 1142
9437530176bc
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/streams.h.md	Thu Jan 23 01:33:36 2025 +0100
@@ -0,0 +1,30 @@
+# streams.h
+
+UCX provides some utilities for routine tasks.
+
+The most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
+bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
+fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
+a UCX buffer or vice-versa.
+
+The following example shows, how easy it is 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");
+    if (fout != stdout) {
+        fclose(fout);
+    }
+}
+```

mercurial