ostream.h revision 34d5077c37dc6224a2d430a72ae51a3f38e9e4f6
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen /* All of the istream was successfully sent to ostream. */
be5c76fabc7439fd33bc799bc3ab3f570799977bTimo Sirainen /* Caller needs to wait for more input from non-blocking istream. */
d176f84ce5ca2073f4dfbafb457b9c74f6bf0d76Timo Sirainen /* Caller needs to wait for output to non-blocking ostream.
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen o_stream_set_flush_pending() is automatically called. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen /* Read from istream failed. See istream->stream_errno. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen /* Write to ostream failed. See ostream->stream_errno. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen /* Number of bytes sent via o_stream_send*() and similar functions.
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen This is counting the input data. For example with a compressed
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen ostream this is counting the uncompressed bytes. The compressed
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen bytes could be counted from the parent ostream's offset.
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen Seeking to a specified offset only makes sense if there is no
be5c76fabc7439fd33bc799bc3ab3f570799977bTimo Sirainen difference between input and output data sizes (e.g. there are no
be5c76fabc7439fd33bc799bc3ab3f570799977bTimo Sirainen wrapper ostreams changing the data). */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen /* errno for the last operation send/seek operation. cleared before
43d3ea2780b5f8557ede7b4c039e8f56cb8d357dTimo Sirainen each call. */
43d3ea2780b5f8557ede7b4c039e8f56cb8d357dTimo Sirainen /* overflow is set when some of the data given to send()
43d3ea2780b5f8557ede7b4c039e8f56cb8d357dTimo Sirainen functions was neither sent nor buffered. It's never unset inside
43d3ea2780b5f8557ede7b4c039e8f56cb8d357dTimo Sirainen ostream code. */
43d3ea2780b5f8557ede7b4c039e8f56cb8d357dTimo Sirainen /* o_stream_send() writes all the data or returns failure */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Returns 1 if all data is sent (not necessarily flushed), 0 if not.
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen Pretty much the only real reason to return 0 is if you wish to send more
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen data to client which isn't buffered, eg. o_stream_send_istream(). */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainentypedef int stream_flush_callback_t(void *context);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainentypedef void ostream_callback_t(void *context);
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainen/* Create new output stream from given file descriptor.
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainen If max_buffer_size is 0, an "optimal" buffer size is used (max 128kB). */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenstruct ostream *o_stream_create_fd(int fd, size_t max_buffer_size);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* The fd is set to -1 immediately to avoid accidentally closing it twice. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenstruct ostream *o_stream_create_fd_autoclose(int *fd, size_t max_buffer_size);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Create an output stream from a regular file which begins at given offset.
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen If offset==(uoff_t)-1, the current offset isn't known. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Siraineno_stream_create_fd_file(int fd, uoff_t offset, bool autoclose_fd);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenstruct ostream *o_stream_create_fd_file_autoclose(int *fd, uoff_t offset);
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainen/* Create an output stream to a buffer. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenstruct ostream *o_stream_create_buffer(buffer_t *buf);
9ed2951bd0bb1878a27437d7c00611b2baadd614Timo Sirainen/* Create an output streams that always fails the writes. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenstruct ostream *o_stream_create_error(int stream_errno);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Siraineno_stream_create_error_str(int stream_errno, const char *fmt, ...)
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Create an output stream that simply passes through data. This is mainly
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainen useful as a wrapper when combined with destroy callbacks. */
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainenstruct ostream *o_stream_create_passthrough(struct ostream *output);
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainen/* Set name (e.g. path) for output stream. */
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainenvoid o_stream_set_name(struct ostream *stream, const char *name);
7569ab8537418b7fc369265f26595b0ef9e4cb35Timo Sirainen/* Get output stream's name. Returns "" if stream has no name. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenconst char *o_stream_get_name(struct ostream *stream);
9ed2951bd0bb1878a27437d7c00611b2baadd614Timo Sirainen/* Return file descriptor for stream, or -1 if none is available. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Returns error string for the previous error. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenconst char *o_stream_get_error(struct ostream *stream);
798cfe56c9871262770384da1239162b3800cce1Timo Sirainen/* Close this stream (but not its parents) and unreference it. */
798cfe56c9871262770384da1239162b3800cce1Timo Sirainenvoid o_stream_destroy(struct ostream **stream);
798cfe56c9871262770384da1239162b3800cce1Timo Sirainen/* Reference counting. References start from 1, so calling o_stream_unref()
798cfe56c9871262770384da1239162b3800cce1Timo Sirainen destroys the stream if o_stream_ref() is never used. */
798cfe56c9871262770384da1239162b3800cce1Timo Sirainen/* Unreferences the stream and sets stream pointer to NULL. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Call the given callback function when stream is destroyed. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenvoid o_stream_add_destroy_callback(struct ostream *stream,
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen#define o_stream_add_destroy_callback(stream, callback, context) \
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen CALLBACK_TYPECHECK(callback, void (*)(typeof(context))), \
47bb4a7615c85f212f061499f04f121d6d625387Timo Sirainen/* Remove the destroy callback. */
47bb4a7615c85f212f061499f04f121d6d625387Timo Sirainenvoid o_stream_remove_destroy_callback(struct ostream *stream,
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Mark the stream and all of its parent streams closed. Nothing will be
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen sent after this call. */
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen/* Set IO_WRITE callback. Default will just try to flush the output and
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen finishes when the buffer is empty. */
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainenvoid o_stream_set_flush_callback(struct ostream *stream,
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen#define o_stream_set_flush_callback(stream, callback, context) \
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen CALLBACK_TYPECHECK(callback, int (*)(typeof(context))), \
fc8d5f0ac909cca77840538e8beef98a8d40c21cTimo Sirainenvoid o_stream_unset_flush_callback(struct ostream *stream);
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen/* Change the maximum size for stream's output buffer to grow. */
fc8d5f0ac909cca77840538e8beef98a8d40c21cTimo Sirainenvoid o_stream_set_max_buffer_size(struct ostream *stream, size_t max_size);
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen/* Returns the current max. buffer size. */
fc8d5f0ac909cca77840538e8beef98a8d40c21cTimo Sirainensize_t o_stream_get_max_buffer_size(struct ostream *stream);
33dd58ab84a020c4f061d2f6031eb6d4c168df1bTimo Sirainen/* Delays sending as far as possible, writing only full buffers. Also sets
33dd58ab84a020c4f061d2f6031eb6d4c168df1bTimo Sirainen TCP_CORK on if supported. */
33dd58ab84a020c4f061d2f6031eb6d4c168df1bTimo Sirainen/* Try to flush the buffer by calling o_stream_flush() and remove TCP_CORK.
5d4855d7b4dcffb6975ed8e3c9c376dac74e5c8aTimo Sirainen Note that after this o_stream_flush() must be called, unless the stream
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen ignores errors. */
798cfe56c9871262770384da1239162b3800cce1Timo Sirainenbool o_stream_is_corked(struct ostream *stream);
82f53ea81671bcc7b9bf24a34b04a4ba2752efd3Timo Sirainen/* Try to flush the output stream. If o_stream_nsend*() had been used and
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainen the stream had overflown, return error. Returns 1 if all data is sent,
82f53ea81671bcc7b9bf24a34b04a4ba2752efd3Timo Sirainen 0 there's still buffered data, -1 if error. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Set "flush pending" state of stream. If set, the flush callback is called
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen when more data is allowed to be sent, even if the buffer itself is empty. */
ce6b6093957885a74fd6e85c18801dbb727d61ecTimo Sirainenvoid o_stream_set_flush_pending(struct ostream *stream, bool set);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Returns number of bytes currently in buffer. */
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainensize_t o_stream_get_buffer_used_size(const struct ostream *stream) ATTR_PURE;
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* Returns number of bytes we can still write without failing. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainensize_t o_stream_get_buffer_avail_size(const struct ostream *stream) ATTR_PURE;
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen/* Seek to specified position from beginning of file. This works only for
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen files. Returns 1 if successful, -1 if error. */
8eb94c5190ba09bb6f6f068eec7bf96750f08d1dTimo Sirainenint o_stream_seek(struct ostream *stream, uoff_t offset);
e9503210d3521a6833ed62dc332fc42ffb0e7a13Timo Sirainen/* Returns number of bytes sent, -1 = error */
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainenssize_t o_stream_send(struct ostream *stream, const void *data, size_t size);
9261dbf0675204898c6557591c7aa376e23a52b2Timo Sirainenssize_t o_stream_sendv(struct ostream *stream, const struct const_iovec *iov,
e9503210d3521a6833ed62dc332fc42ffb0e7a13Timo Sirainen unsigned int iov_count);
ce6b6093957885a74fd6e85c18801dbb727d61ecTimo Sirainenssize_t o_stream_send_str(struct ostream *stream, const char *str);
e9503210d3521a6833ed62dc332fc42ffb0e7a13Timo Sirainen/* Send with delayed error handling. o_stream_flush() or
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainen o_stream_ignore_last_errors() must be called after these functions before
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen the stream is destroyed. If any of the data can't be sent due to stream's
31597236d79ac38a5cea7ab65a9d0a3df64ed201Timo Sirainen buffer getting full, all further nsends are ignores and o_stream_flush()
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen will fail. */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenvoid o_stream_nsend(struct ostream *stream, const void *data, size_t size);
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenvoid o_stream_nsendv(struct ostream *stream, const struct const_iovec *iov,
70c181da837ed85fc5b0426c010b65609bda5329Timo Sirainen unsigned int iov_count);
70c181da837ed85fc5b0426c010b65609bda5329Timo Sirainenvoid o_stream_nsend_str(struct ostream *stream, const char *str);
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainenstatic inline int o_stream_nfinish(struct ostream *stream)
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen/* Marks the stream's error handling as completed to avoid i_panic() on
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainenvoid o_stream_ignore_last_errors(struct ostream *stream);
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen/* If error handling is disabled, the i_panic() on destroy is never called.
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen This function can be called immediately after the stream is created.
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen When creating wrapper streams, they copy this behavior from the parent
3cf67672fdc87583cb23ce088c95bb5dee60e74dTimo Sirainenvoid o_stream_set_no_error_handling(struct ostream *stream, bool set);
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen/* Send all of the instream to outstream.
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Sirainen On non-failure instream is skips over all data written to outstream.
8eb94c5190ba09bb6f6f068eec7bf96750f08d1dTimo Sirainen This means that the number of bytes written to outstream is always equal to
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainen the number of bytes skipped in instream.
e9503210d3521a6833ed62dc332fc42ffb0e7a13Timo Sirainen It's also possible to use this function to copy data within same file
e9503210d3521a6833ed62dc332fc42ffb0e7a13Timo Sirainen descriptor, even if the source and destination overlaps. If the file must
e9503210d3521a6833ed62dc332fc42ffb0e7a13Timo Sirainen be grown, you have to do it manually before calling this function. */
adc409a7ac9689d3baf811712ad5a5432cab2d87Timo Siraineno_stream_send_istream(struct ostream *outstream, struct istream *instream);
b321df9603081896b70ec44635af96d674a9839aTimo Sirainen/* Same as o_stream_send_istream(), but assume that reads and writes will
ce6b6093957885a74fd6e85c18801dbb727d61ecTimo Sirainen succeed. If not, o_stream_flush() will fail with the correct error
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen message (even istream's). */
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainenvoid o_stream_nsend_istream(struct ostream *outstream, struct istream *instream);
b44650b0f48a4b5f0dc240ed836833a00b643b9fTimo Sirainen/* Write data to specified offset. Returns 0 if successful, -1 if error. */
b44650b0f48a4b5f0dc240ed836833a00b643b9fTimo Sirainenint o_stream_pwrite(struct ostream *stream, const void *data, size_t size,
2e29e4797a48d78d669821722bdb54fd0a1d3b94Timo Sirainen/* If there are any I/O loop items associated with the stream, move all of
226259ee6fb9830dafc1a5ba1e95bf5a4345b406Timo Sirainen them to current_ioloop. */