istream.h revision 699fdc186f982f70d990820796eaa0f12133e27c
95a1a5195d56f3cf5d1e529aad668f87ad3b979bTimo Sirainen/* Note that some systems (Solaris) may use a macro to redefine struct stat */
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen unsigned int mmaped:1; /* be careful when copying data */
105addcb709523868418cc3e3baad7ad3453a91eTimo Sirainen unsigned int blocking:1; /* read() shouldn't return 0 */
105addcb709523868418cc3e3baad7ad3453a91eTimo Sirainen unsigned int seekable:1; /* we can seek() backwards */
105addcb709523868418cc3e3baad7ad3453a91eTimo Sirainen unsigned int eof:1; /* read() has reached to end of file
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen (but may still be data available in buffer) */
aef92409cf369afdd2ecd81a4f80083cd4082f46Timo Sirainentypedef void istream_callback_t(void *context);
aef92409cf369afdd2ecd81a4f80083cd4082f46Timo Sirainenstruct istream *i_stream_create_fd(int fd, size_t max_buffer_size,
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenstruct istream *i_stream_create_mmap(int fd, size_t block_size,
1175f27441385a7011629f295f42708f9a3a4ffcTimo Sirainenstruct istream *i_stream_create_from_data(const void *data, size_t size);
1175f27441385a7011629f295f42708f9a3a4ffcTimo Sirainenstruct istream *i_stream_create_limit(struct istream *input, uoff_t v_size);
56f45b3f3ae20e5c933701f4657dda5ef1916855Timo Sirainen/* i_stream_close() + i_stream_unref() */
7797aa2479e99aeb71057b7a2584b2cb72e4d3f8Timo Sirainenvoid i_stream_destroy(struct istream **stream);
7797aa2479e99aeb71057b7a2584b2cb72e4d3f8Timo Sirainen/* Reference counting. References start from 1, so calling i_stream_unref()
7797aa2479e99aeb71057b7a2584b2cb72e4d3f8Timo Sirainen destroys the stream if i_stream_ref() is never used. */
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainen/* Unreferences the stream and sets stream pointer to NULL. */
1175f27441385a7011629f295f42708f9a3a4ffcTimo Sirainen/* Call the given callback function when stream is destroyed. */
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenvoid i_stream_set_destroy_callback(struct istream *stream,
51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen#define i_stream_set_destroy_callback(stream, callback, context) \
51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen CONTEXT_CALLBACK(i_stream_set_destroy_callback, istream_callback_t, \
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen/* Return file descriptor for stream, or -1 if none is available. */
1175f27441385a7011629f295f42708f9a3a4ffcTimo Sirainen/* Mark the stream closed. Any reads after this will return -1. The data
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen already read can still be used. */
1175f27441385a7011629f295f42708f9a3a4ffcTimo Sirainen/* Sync the stream with the underlying backend, ie. if a file has been
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen modified, flush any cached data. */
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen/* Change the maximum size for stream's input buffer to grow. Useful only
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen for buffered streams (currently only file). */
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenvoid i_stream_set_max_buffer_size(struct istream *stream, size_t max_size);
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen/* Returns number of bytes read if read was ok, -1 if EOF or error, -2 if the
659fe5d24825b160cae512538088020d97a60239Timo Sirainen input buffer is full. */
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen/* Skip forward a number of bytes. Never fails, the next read tells if it
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen was successful. */
659fe5d24825b160cae512538088020d97a60239Timo Sirainenvoid i_stream_skip(struct istream *stream, uoff_t count);
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen/* Seek to specified position from beginning of file. Never fails, the next
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen read tells if it was successful. This works only for files. */
232d5bef3c709e90e24f0874a36854b92187bb6cTimo Sirainenvoid i_stream_seek(struct istream *stream, uoff_t v_offset);
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainen/* Like i_stream_seek(), but also giving a hint that after reading some data
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainen we could be seeking back to this mark or somewhere after it. If input
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainen stream's implementation is slow in seeking backwards, it can use this hint
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainen to cache some of the data in memory. */
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainenvoid i_stream_seek_mark(struct istream *stream, uoff_t v_offset);
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainen/* Returns struct stat, or NULL if error. As the underlying stream may not be
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainen a file, only some of the fields might be set, others would be zero.
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainen st_size is always set, and if it's not known, it's -1.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen If exact=FALSE, the stream may not return exactly correct values, but the
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen returned values can be compared to see if anything had changed (eg. in
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainen compressed stream st_size could be compressed size) */
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainenconst struct stat *i_stream_stat(struct istream *stream, bool exact);
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainen/* Returns TRUE if there are any bytes left to be read or in buffer. */
faed8babca9914257f34fb2e603d74016d563b2dTimo Sirainenbool i_stream_have_bytes_left(const struct istream *stream) ATTR_PURE;
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen/* Gets the next line from stream and returns it, or NULL if more data is
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen needed to make a full line. Note that if the stream ends with LF not being
a928e7efabb1672b1476e597106d4b4b81ac6f3cTimo Sirainen the last character, this function doesn't return the last line. */
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainenchar *i_stream_next_line(struct istream *stream);
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen/* Like i_stream_next_line(), but reads for more data if needed. Returns NULL
838f56174b963779a88083a0d0e85b30d2d846e7Timo Sirainen if more data is needed or error occurred. */
894987bf45718f8849cc3898afdfb1ac3cfa2445Timo Sirainenchar *i_stream_read_next_line(struct istream *stream);
894987bf45718f8849cc3898afdfb1ac3cfa2445Timo Sirainen/* Returns pointer to beginning of read data, or NULL if there's no data
838f56174b963779a88083a0d0e85b30d2d846e7Timo Sirainenconst unsigned char *
7797aa2479e99aeb71057b7a2584b2cb72e4d3f8Timo Siraineni_stream_get_data(const struct istream *stream, size_t *size_r);
d143077bd518de129b8d446fb58e003903e50867Timo Sirainen/* Like i_stream_get_data(), but returns non-const data. This only works with
d143077bd518de129b8d446fb58e003903e50867Timo Sirainen buffered streams (currently only file), others return NULL. */
d143077bd518de129b8d446fb58e003903e50867Timo Sirainenunsigned char *i_stream_get_modifiable_data(const struct istream *stream,
5a07b37a9df398b5189c14872a600384208ab74bTimo Sirainen/* Like i_stream_get_data(), but read more when needed. Returns 1 if more
5a07b37a9df398b5189c14872a600384208ab74bTimo Sirainen than threshold bytes are available, 0 if as much or less, -1 if error or
bbf796c17f02538058d7559bfe96d677e5b55015Timo Sirainen EOF with no bytes read that weren't already in buffer, or -2 if stream's
838f56174b963779a88083a0d0e85b30d2d846e7Timo Sirainen input buffer is full. */
5a07b37a9df398b5189c14872a600384208ab74bTimo Sirainenint i_stream_read_data(struct istream *stream, const unsigned char **data_r,
5a07b37a9df398b5189c14872a600384208ab74bTimo Sirainen/* Append external data to input stream. Returns TRUE if successful, FALSE if
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen there is not enough space in the stream. */
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainenbool i_stream_add_data(struct istream *stream, const unsigned char *data,