ostream.h revision 8b247780e911909a9fdc47f69ce6d1478902ad98
6cc0546c058f3e6253c6f99727b28dd602712974Timo Sirainen /* errno for the last operation send/seek operation. cleared before
6cc0546c058f3e6253c6f99727b28dd602712974Timo Sirainen each call. */
6cc0546c058f3e6253c6f99727b28dd602712974Timo Sirainen /* errno of the last failed send/seek. never cleared. */
0ce5f96804e81cb0f857e7df32c0272f1eed9377Timo Sirainen /* overflow is set when some of the data given to send()
0ce5f96804e81cb0f857e7df32c0272f1eed9377Timo Sirainen functions was neither sent nor buffered. It's never unset inside
0ce5f96804e81cb0f857e7df32c0272f1eed9377Timo Sirainen ostream code. */
211ed7806d8715ec2280ffbf5d10f0d6e4f1beb2Timo Sirainen/* Returns 1 if all data is sent (not necessarily flushed), 0 if not.
211ed7806d8715ec2280ffbf5d10f0d6e4f1beb2Timo Sirainen Pretty much the only real reason to return 0 is if you wish to send more
211ed7806d8715ec2280ffbf5d10f0d6e4f1beb2Timo Sirainen data to client which isn't buffered, eg. o_stream_send_istream(). */
211ed7806d8715ec2280ffbf5d10f0d6e4f1beb2Timo Sirainentypedef int stream_flush_callback_t(void *context);
9b7eeffb5752b500ac62ba1fd01c4a8c4ada14e9Timo Sirainen/* Create new output stream from given file descriptor.
9b7eeffb5752b500ac62ba1fd01c4a8c4ada14e9Timo Sirainen If max_buffer_size is 0, an "optimal" buffer size is used (max 128kB). */
93fa87cf1a96c4f279ec4f5c311820313ba12c34Timo Siraineno_stream_create_fd(int fd, size_t max_buffer_size, bool autoclose_fd);
93fa87cf1a96c4f279ec4f5c311820313ba12c34Timo Sirainen/* Create an output stream from a regular file which begins at given offset.
93fa87cf1a96c4f279ec4f5c311820313ba12c34Timo Sirainen If offset==(uoff_t)-1, the current offset isn't known. */
93fa87cf1a96c4f279ec4f5c311820313ba12c34Timo Siraineno_stream_create_fd_file(int fd, uoff_t offset, bool autoclose_fd);
b565a6a7a66fb9f224d00c06a950e3c1c585c18eTimo Sirainen/* Create an output stream to a buffer. */
b565a6a7a66fb9f224d00c06a950e3c1c585c18eTimo Sirainenstruct ostream *o_stream_create_buffer(buffer_t *buf);
8cb72c59d5ea4e9e5f638d7ec840bb853f5a188eTimo Sirainen/* Set name (e.g. path) for output stream. */
8cb72c59d5ea4e9e5f638d7ec840bb853f5a188eTimo Sirainenvoid o_stream_set_name(struct ostream *stream, const char *name);
8cb72c59d5ea4e9e5f638d7ec840bb853f5a188eTimo Sirainen/* Get output stream's name. Returns "" if stream has no name. */
8cb72c59d5ea4e9e5f638d7ec840bb853f5a188eTimo Sirainenconst char *o_stream_get_name(struct ostream *stream);
8b247780e911909a9fdc47f69ce6d1478902ad98Timo Sirainen/* Return file descriptor for stream, or -1 if none is available. */
cd56a23e21f1df3f79648cf07e2f4385e2fadebbTimo Sirainen/* o_stream_close() + o_stream_unref() */
cd56a23e21f1df3f79648cf07e2f4385e2fadebbTimo Sirainenvoid o_stream_destroy(struct ostream **stream);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Reference counting. References start from 1, so calling o_stream_unref()
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen destroys the stream if o_stream_ref() is never used. */
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainen/* Unreferences the stream and sets stream pointer to NULL. */
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Mark the stream closed. Nothing will be sent after this call. */
211ed7806d8715ec2280ffbf5d10f0d6e4f1beb2Timo Sirainen/* Set IO_WRITE callback. Default will just try to flush the output and
211ed7806d8715ec2280ffbf5d10f0d6e4f1beb2Timo Sirainen finishes when the buffer is empty. */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenvoid o_stream_set_flush_callback(struct ostream *stream,
59151b71059df1190acd75d8717ed04a7920c862Timo Sirainen#define o_stream_set_flush_callback(stream, callback, context) \
59151b71059df1190acd75d8717ed04a7920c862Timo Sirainen CONTEXT_CALLBACK(o_stream_set_flush_callback, stream_flush_callback_t, \
59151b71059df1190acd75d8717ed04a7920c862Timo Sirainenvoid o_stream_unset_flush_callback(struct ostream *stream);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Change the maximum size for stream's output buffer to grow. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenvoid o_stream_set_max_buffer_size(struct ostream *stream, size_t max_size);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Delays sending as far as possible, writing only full buffers. Also sets
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen TCP_CORK on if supported. */
683eebe490bbe5caec246c535a10ea9f93f5c330Timo Sirainen/* Try to flush the output stream. Returns 1 if all sent, 0 if not,
683eebe490bbe5caec246c535a10ea9f93f5c330Timo Sirainen -1 if error. */
5238111c460098d9cc8cc22527026138a278b9a4Timo Sirainen/* Set "flush pending" state of stream. If set, the flush callback is called
5238111c460098d9cc8cc22527026138a278b9a4Timo Sirainen when more data is allowed to be sent, even if the buffer itself is empty. */
6ef7e31619edfaa17ed044b45861d106a86191efTimo Sirainenvoid o_stream_set_flush_pending(struct ostream *stream, bool set);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Returns number of bytes currently in buffer. */
68a4946b12583b88fa802e52ebee45cd96056772Timo Sirainensize_t o_stream_get_buffer_used_size(const struct ostream *stream) ATTR_PURE;
de954ff15b495be13007a8aca2c09fd1d356a283Timo Sirainen/* Returns number of bytes we can still write without failing. */
de954ff15b495be13007a8aca2c09fd1d356a283Timo Sirainensize_t o_stream_get_buffer_avail_size(const struct ostream *stream) ATTR_PURE;
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Seek to specified position from beginning of file. This works only for
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen files. Returns 1 if successful, -1 if error. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenint o_stream_seek(struct ostream *stream, uoff_t offset);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Returns number of bytes sent, -1 = error */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenssize_t o_stream_send(struct ostream *stream, const void *data, size_t size);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenssize_t o_stream_sendv(struct ostream *stream, const struct const_iovec *iov,
0ce5f96804e81cb0f857e7df32c0272f1eed9377Timo Sirainen unsigned int iov_count);
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenssize_t o_stream_send_str(struct ostream *stream, const char *str);
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen/* Send with delayed error handling. o_stream_has_errors() or
ceb43cc04edb94445fab8f914bc4da6d740403d1Timo Sirainen o_stream_ignore_last_errors() must be called after these functions before
ceb43cc04edb94445fab8f914bc4da6d740403d1Timo Sirainen the stream is destroyed. */
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainenvoid o_stream_nsend(struct ostream *stream, const void *data, size_t size);
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainenvoid o_stream_nsendv(struct ostream *stream, const struct const_iovec *iov,
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen unsigned int iov_count);
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainenvoid o_stream_nsend_str(struct ostream *stream, const char *str);
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen/* Flushes the stream and returns -1 if stream->last_failed_errno is
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen non-zero. Marks the stream's error handling as completed. errno is also set
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen to last_failed_errno. */
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen/* Marks the stream's error handling as completed to avoid i_panic() on
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainenvoid o_stream_ignore_last_errors(struct ostream *stream);
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen/* If error handling is disabled, the i_panic() on destroy is never called.
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen This function can be called immediately after the stream is created.
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen When creating wrapper streams, they copy this behavior from the parent
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainenvoid o_stream_set_no_error_handling(struct ostream *stream, bool set);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Send data from input stream. Returns number of bytes sent, or -1 if error.
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen Note that this function may block if either instream or outstream is
d7e72877b7a5085c3addf9729d0bfbe1b5357853Timo Sirainen Also note that this function may not add anything to the output buffer, so
d7e72877b7a5085c3addf9729d0bfbe1b5357853Timo Sirainen if you want the flush callback to be called when more data can be written,
d7e72877b7a5085c3addf9729d0bfbe1b5357853Timo Sirainen you'll need to call o_stream_set_flush_pending() manually.
03f5c621d06d6b6d77a145196c9633a7aa64dc78Timo Sirainen It's also possible to use this function to copy data within same file
03f5c621d06d6b6d77a145196c9633a7aa64dc78Timo Sirainen descriptor. If the file must be grown, you have to do it manually before
03f5c621d06d6b6d77a145196c9633a7aa64dc78Timo Sirainen calling this function. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenoff_t o_stream_send_istream(struct ostream *outstream,
8cdb3234fe3c77e477c7a0e6934678f58fc54d4dTimo Sirainen/* Write data to specified offset. Returns 0 if successful, -1 if error. */
8cdb3234fe3c77e477c7a0e6934678f58fc54d4dTimo Sirainenint o_stream_pwrite(struct ostream *stream, const void *data, size_t size,
71da447014454c84828d9dface77219875554d7dTimo Sirainen/* If there are any I/O loop items associated with the stream, move all of
71da447014454c84828d9dface77219875554d7dTimo Sirainen them to current_ioloop. */