1 #pragma once 2 3 #include <reproc/reproc.h> 4 5 #ifdef __cplusplus 6 extern "C" { 7 #endif 8 9 /*! Used by `reproc_drain` to provide data to the caller. Each time data is 10 read, `function` is called with `context`. If a sink returns a non-zero value, 11 `reproc_drain` will return immediately with the same value. */ 12 typedef struct reproc_sink { 13 int (*function)(REPROC_STREAM stream, 14 const uint8_t *buffer, 15 size_t size, 16 void *context); 17 void *context; 18 } reproc_sink; 19 20 /*! Pass `REPROC_SINK_NULL` as the sink for output streams that have not been 21 redirected to a pipe. */ 22 REPROC_EXPORT extern const reproc_sink REPROC_SINK_NULL; 23 24 /*! 25 Reads from the child process stdout and stderr until an error occurs or both 26 streams are closed. The `out` and `err` sinks receive the output from stdout and 27 stderr respectively. The same sink may be passed to both `out` and `err`. 28 29 `reproc_drain` always starts by calling both sinks once with an empty buffer and 30 `stream` set to `REPROC_STREAM_IN` to give each sink the chance to process all 31 output from the previous call to `reproc_drain` one by one. 32 33 When a stream is closed, its corresponding `sink` is called once with `size` set 34 to zero. 35 36 Note that his function returns 0 instead of `REPROC_EPIPE` when both output 37 streams of the child process are closed. 38 39 Actionable errors: 40 - `REPROC_ETIMEDOUT` 41 */ 42 REPROC_EXPORT int 43 reproc_drain(reproc_t *process, reproc_sink out, reproc_sink err); 44 45 /*! 46 Appends the output of a process (stdout and stderr) to the value of `output`. 47 `output` must point to either `NULL` or a NUL-terminated string. 48 49 Calls `realloc` as necessary to make space in `output` to store the output of 50 the child process. Make sure to always call `reproc_free` on the value of 51 `output` after calling `reproc_drain` (even if it fails). 52 53 Because the resulting sink does not store the output size, `strlen` is called 54 each time data is read to calculate the current size of the output. This might 55 cause performance problems when draining processes that produce a lot of output. 56 57 Similarly, this sink will not work on processes that have NUL terminators in 58 their output because `strlen` is used to calculate the current output size. 59 60 Returns `REPROC_ENOMEM` if a call to `realloc` fails. `output` will contain any 61 output read from the child process, preceeded by whatever was stored in it at 62 the moment its corresponding sink was passed to `reproc_drain`. 63 64 The `drain` example shows how to use `reproc_sink_string`. 65 ``` 66 */ 67 REPROC_EXPORT reproc_sink reproc_sink_string(char **output); 68 69 /*! Discards the output of a process. */ 70 REPROC_EXPORT reproc_sink reproc_sink_discard(void); 71 72 /*! Calls `free` on `ptr` and returns `NULL`. Use this function to free memory 73 allocated by `reproc_sink_string`. This avoids issues with allocating across 74 module (DLL) boundaries on Windows. */ 75 REPROC_EXPORT void *reproc_free(void *ptr); 76 77 #ifdef __cplusplus 78 } 79 #endif 80