istream.h revision 602a0434db30d8e3292d1c161a803d96a879a74f
03f5c621d06d6b6d77a145196c9633a7aa64dc78Timo Sirainen unsigned int mmaped:1; /* be careful when copying data */
411d6baa37f31d90730e90c4a28c43e1974bbe58Timo Sirainen unsigned int seekable:1; /* we can seek() backwards */
7e1f68ad71d3485f1882142837b01f7a98ca8467Timo Sirainen unsigned int eof:1; /* read() has reached to end of file
7e1f68ad71d3485f1882142837b01f7a98ca8467Timo Sirainen (but may still be data available in buffer) */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenstruct istream *i_stream_create_file(int fd, pool_t pool,
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenstruct istream *i_stream_create_mmap(int fd, pool_t pool, size_t block_size,
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenstruct istream *i_stream_create_from_data(pool_t pool, const void *data,
dd62b77c932d1b518f2a3e4bf80e36542becc256Timo Sirainenstruct istream *i_stream_create_limit(pool_t pool, struct istream *input,
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Reference counting. References start from 1, so calling i_stream_unref()
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen destroys the stream if i_stream_ref() is never used. */
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Return file descriptor for stream, or -1 if none is available. */
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Mark the stream closed. Any reads after this will return -1. The data
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen already read can still be used. */
07e4875d250e7a7157cd99132aafc773cf3cdf83Timo Sirainen/* Sync the stream with the underlying backend, ie. if a file has been
07e4875d250e7a7157cd99132aafc773cf3cdf83Timo Sirainen modified, flush any cached data. */
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Change the maximum size for stream's input buffer to grow. Useful only
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen for buffered streams (currently only file). */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenvoid i_stream_set_max_buffer_size(struct istream *stream, size_t max_size);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Returns number of bytes read if read was ok, -1 if EOF or error, -2 if the
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen input buffer is full. */
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Skip forward a number of bytes. Never fails, the next read tells if it
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen was successful. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenvoid i_stream_skip(struct istream *stream, uoff_t count);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Seek to specified position from beginning of file. Never fails, the next
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen read tells if it was successful. This works only for files. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenvoid i_stream_seek(struct istream *stream, uoff_t v_offset);
602a0434db30d8e3292d1c161a803d96a879a74fTimo Sirainen/* Like i_stream_seek(), but also giving a hint that after reading some data
602a0434db30d8e3292d1c161a803d96a879a74fTimo Sirainen we could be seeking back to this mark or somewhere after it. If input
602a0434db30d8e3292d1c161a803d96a879a74fTimo Sirainen stream's implementation is slow in seeking backwards, it can use this hint
602a0434db30d8e3292d1c161a803d96a879a74fTimo Sirainen to cache some of the data in memory. */
602a0434db30d8e3292d1c161a803d96a879a74fTimo Sirainenvoid i_stream_seek_mark(struct istream *stream, uoff_t v_offset);
07e4875d250e7a7157cd99132aafc773cf3cdf83Timo Sirainen/* Returns struct stat, or NULL if error. As the underlying stream may not be
07e4875d250e7a7157cd99132aafc773cf3cdf83Timo Sirainen a file, only some of the fields might be set, others would be zero.
07e4875d250e7a7157cd99132aafc773cf3cdf83Timo Sirainen st_size is always set, and if it's not known, it's -1. */
07e4875d250e7a7157cd99132aafc773cf3cdf83Timo Sirainenconst struct stat *i_stream_stat(struct istream *stream);
7e1f68ad71d3485f1882142837b01f7a98ca8467Timo Sirainen/* Returns TRUE if there are any bytes left to be read or in buffer. */
7e1f68ad71d3485f1882142837b01f7a98ca8467Timo Sirainenint i_stream_have_bytes_left(struct istream *stream);
89e195dfb5c4b0efd9b9f459771a4467674e5b1fTimo Sirainen/* Gets the next line from stream and returns it, or NULL if more data is
e0c3d5460d1cc0c440cb7723c8c2eef8d0afe9b9Timo Sirainen needed to make a full line. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenchar *i_stream_next_line(struct istream *stream);
89e195dfb5c4b0efd9b9f459771a4467674e5b1fTimo Sirainen/* Like i_stream_next_line(), but reads for more data if needed. Returns NULL
137ea7ca34005345aa2304a940149b7f3774d727Timo Sirainen if more data is needed or error occurred. */
89e195dfb5c4b0efd9b9f459771a4467674e5b1fTimo Sirainenchar *i_stream_read_next_line(struct istream *stream);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Returns pointer to beginning of read data, or NULL if there's no data
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenconst unsigned char *i_stream_get_data(struct istream *stream, size_t *size);
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Like i_stream_get_data(), but returns non-const data. This only works with
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen buffered streams (currently only file), others return NULL. */
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenunsigned char *i_stream_get_modifyable_data(struct istream *stream,
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen/* Like i_stream_get_data(), but read more when needed. Returns 1 if more
ecc81625167ed96c04c02aa190a1ea5baa65b474Timo Sirainen than threshold bytes are available, 0 if less, -1 if error or EOF with no
65cb456a072219fa35b55695d476b0bf51e2d735Timo Sirainen bytes read that weren't already in buffer, or -2 if stream's input buffer
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenint i_stream_read_data(struct istream *stream, const unsigned char **data,