istream.h revision 49e358eebea107aad9919dcc4bd88cee8519ba2e
16f816d3f3c32ae3351834253f52ddd0212bcbf3Timo Sirainen/* Note that some systems (Solaris) may use a macro to redefine struct stat */
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen unsigned int mmaped:1; /* be careful when copying data */
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen unsigned int seekable:1; /* we can seek() backwards */
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen unsigned int eof:1; /* read() has reached to end of file
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen (but may still be data available in buffer) */
61530b48694398df42744204e35535dbe3f745c4Timo Sirainenstruct istream *i_stream_create_file(int fd, pool_t pool,
3ddbbe03fe74b3ee7b1dff4e08ec706d7880d052Timo Sirainenstruct istream *i_stream_create_mmap(int fd, pool_t pool, size_t block_size,
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenstruct istream *i_stream_create_from_data(pool_t pool, const void *data,
6789ed17e7ca4021713507baf0dcf6979bb42e0cTimo Sirainenstruct istream *i_stream_create_limit(pool_t pool, struct istream *input,
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* i_stream_close() + i_stream_unref() */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenvoid i_stream_destroy(struct istream **stream);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Reference counting. References start from 1, so calling i_stream_unref()
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen destroys the stream if i_stream_ref() is never used. */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Unreferences the stream and sets stream pointer to NULL. */
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen/* Return file descriptor for stream, or -1 if none is available. */
6789ed17e7ca4021713507baf0dcf6979bb42e0cTimo Sirainen/* Mark the stream closed. Any reads after this will return -1. The data
8d80659e504ffb34bb0c6a633184fece35751b18Timo Sirainen already read can still be used. */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Sync the stream with the underlying backend, ie. if a file has been
6789ed17e7ca4021713507baf0dcf6979bb42e0cTimo Sirainen modified, flush any cached data. */
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen/* Change the maximum size for stream's input buffer to grow. Useful only
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen for buffered streams (currently only file). */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenvoid i_stream_set_max_buffer_size(struct istream *stream, size_t max_size);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Returns number of bytes read if read was ok, -1 if EOF or error, -2 if the
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen input buffer is full. */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Skip forward a number of bytes. Never fails, the next read tells if it
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen was successful. */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenvoid i_stream_skip(struct istream *stream, uoff_t count);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Seek to specified position from beginning of file. Never fails, the next
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen read tells if it was successful. This works only for files. */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenvoid i_stream_seek(struct istream *stream, uoff_t v_offset);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Like i_stream_seek(), but also giving a hint that after reading some data
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen we could be seeking back to this mark or somewhere after it. If input
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen stream's implementation is slow in seeking backwards, it can use this hint
6ef7e31619edfaa17ed044b45861d106a86191efTimo Sirainen to cache some of the data in memory. */
f1e9611e93dcb3b745c1904029084fa81644e1b3Timo Sirainenvoid i_stream_seek_mark(struct istream *stream, uoff_t v_offset);
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen/* Returns struct stat, or NULL if error. As the underlying stream may not be
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen a file, only some of the fields might be set, others would be zero.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen st_size is always set, and if it's not known, it's -1.
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen If exact=FALSE, the stream may not return exactly correct values, but the
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen returned values can be compared to see if anything had changed (eg. in
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen compressed stream st_size could be compressed size) */
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenconst struct stat *i_stream_stat(struct istream *stream, bool exact);
baf1148108b7d9739626b47cc57298c36929586aTimo Sirainen/* Returns TRUE if there are any bytes left to be read or in buffer. */
e60a349c641bb2f4723e4a395a25f55531682d2bTimo Sirainenbool i_stream_have_bytes_left(struct istream *stream);
baf1148108b7d9739626b47cc57298c36929586aTimo Sirainen/* Gets the next line from stream and returns it, or NULL if more data is
baf1148108b7d9739626b47cc57298c36929586aTimo Sirainen needed to make a full line. Note that if the stream ends with LF not being
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen the last character, this function doesn't return the last line. */
4c07b08af30e1065f7022980b60474f229d8cadfTimo Sirainenchar *i_stream_next_line(struct istream *stream);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Like i_stream_next_line(), but reads for more data if needed. Returns NULL
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen if more data is needed or error occurred. */
e60a349c641bb2f4723e4a395a25f55531682d2bTimo Sirainenchar *i_stream_read_next_line(struct istream *stream);
e60a349c641bb2f4723e4a395a25f55531682d2bTimo Sirainen/* Returns pointer to beginning of read data, or NULL if there's no data
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenconst unsigned char *i_stream_get_data(struct istream *stream, size_t *size);
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen/* Like i_stream_get_data(), but returns non-const data. This only works with
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen buffered streams (currently only file), others return NULL. */
fd1f0e9ef52b3e157cfd1a01c464c2ac7458ab17Timo Sirainenunsigned char *i_stream_get_modifyable_data(struct istream *stream,
5ce2084ada06ade9f44fc2914c34658e9a842dc1Timo Sirainen/* Like i_stream_get_data(), but read more when needed. Returns 1 if more
e60a349c641bb2f4723e4a395a25f55531682d2bTimo Sirainen than threshold bytes are available, 0 if less, -1 if error or EOF with no
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainen bytes read that weren't already in buffer, or -2 if stream's input buffer
2767104d81e97a109f0aa9758792bfa1da325a97Timo Sirainenint i_stream_read_data(struct istream *stream, const unsigned char **data,