istream.h revision 7662010b03ffe5f2a6ecf4b4eb220d1c65efea76
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Note that some systems (Solaris) may use a macro to redefine struct stat */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen unsigned int mmaped:1; /* be careful when copying data */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen unsigned int blocking:1; /* read() shouldn't return 0 */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen unsigned int readable_fd:1; /* fd can be read directly if necessary
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen (for sendfile()) */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen unsigned int seekable:1; /* we can seek() backwards */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen unsigned int eof:1; /* read() has reached to end of file
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen (but may still be data available in buffer) */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainentypedef void istream_callback_t(void *context);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenstruct istream *i_stream_create_fd(int fd, size_t max_buffer_size,
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenstruct istream *i_stream_create_mmap(int fd, size_t block_size,
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainenstruct istream *i_stream_create_from_data(const void *data, size_t size);
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainenstruct istream *i_stream_create_limit(struct istream *input, uoff_t v_size);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* i_stream_close() + i_stream_unref() */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_destroy(struct istream **stream);
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen/* Reference counting. References start from 1, so calling i_stream_unref()
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen destroys the stream if i_stream_ref() is never used. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Unreferences the stream and sets stream pointer to NULL. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Call the given callback function when stream is destroyed. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_set_destroy_callback(struct istream *stream,
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen#define i_stream_set_destroy_callback(stream, callback, context) \
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen CONTEXT_CALLBACK(i_stream_set_destroy_callback, istream_callback_t, \
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Return file descriptor for stream, or -1 if none is available. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Mark the stream closed. Any reads after this will return -1. The data
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen already read can still be used. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Sync the stream with the underlying backend, ie. if a file has been
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen modified, flush any cached data. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Change the initial size for stream's input buffer. This basically just
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen grows the read buffer size from the default. This function has no effect
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen unless it's called before reading anything. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_set_init_buffer_size(struct istream *stream, size_t size);
c991d8c2c0d5d6c025e24fc00cb06dd61c42456dTimo Sirainen/* Change the maximum size for stream's input buffer to grow. Useful only
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen for buffered streams (currently only file). */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_set_max_buffer_size(struct istream *stream, size_t max_size);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Enable/disable i_stream[_read]_next_line() returning the last line if it
c991d8c2c0d5d6c025e24fc00cb06dd61c42456dTimo Sirainen doesn't end with LF. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_set_return_partial_line(struct istream *stream, bool set);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Returns number of bytes read if read was ok, -1 if EOF or error, -2 if the
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen input buffer is full. */
c991d8c2c0d5d6c025e24fc00cb06dd61c42456dTimo Sirainen/* Skip forward a number of bytes. Never fails, the next read tells if it
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen was successful. */
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainenvoid i_stream_skip(struct istream *stream, uoff_t count);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Seek to specified position from beginning of file. Never fails, the next
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen read tells if it was successful. This works only for files. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_seek(struct istream *stream, uoff_t v_offset);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Like i_stream_seek(), but also giving a hint that after reading some data
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen we could be seeking back to this mark or somewhere after it. If input
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen stream's implementation is slow in seeking backwards, it can use this hint
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen to cache some of the data in memory. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenvoid i_stream_seek_mark(struct istream *stream, uoff_t v_offset);
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Returns struct stat, or NULL if error. As the underlying stream may not be
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen a file, only some of the fields might be set, others would be zero.
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen st_size is always set, and if it's not known, it's -1.
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen If exact=FALSE, the stream may not return exactly correct values, but the
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen returned values can be compared to see if anything had changed (eg. in
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen compressed stream st_size could be compressed size) */
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainenconst struct stat *i_stream_stat(struct istream *stream, bool exact);
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen/* Similar to i_stream_stat() call. Returns 1 if size was successfully
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen set, 0 if size is unknown, -1 if error. */
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainenint i_stream_get_size(struct istream *stream, bool exact, uoff_t *size_r);
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen/* Returns TRUE if there are any bytes left to be read or in buffer. */
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainenbool i_stream_have_bytes_left(const struct istream *stream) ATTR_PURE;
d06d6667bac64aabe1efb216af56ca45108d63b0Timo Sirainen/* Returns TRUE if there are no bytes buffered and read() returns EOF. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen/* Gets the next line from stream and returns it, or NULL if more data is
c991d8c2c0d5d6c025e24fc00cb06dd61c42456dTimo Sirainen needed to make a full line. i_stream_set_return_partial_line() specifies
503a863a317acba125a4e46435694e35fad769e4Timo Sirainen if the last line should be returned if it doesn't end with LF. */
503a863a317acba125a4e46435694e35fad769e4Timo Sirainenchar *i_stream_next_line(struct istream *stream);
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen/* Like i_stream_next_line(), but reads for more data if needed. Returns NULL
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen if more data is needed or error occurred. */
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainenchar *i_stream_read_next_line(struct istream *stream);
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen/* Returns pointer to beginning of read data, or NULL if there's no data
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainenconst unsigned char *
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Siraineni_stream_get_data(const struct istream *stream, size_t *size_r);
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen/* Like i_stream_get_data(), but returns non-const data. This only works with
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen buffered streams (currently only file), others return NULL. */
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainenunsigned char *i_stream_get_modifiable_data(const struct istream *stream,
86bde2c1838d1ce967fa2b394bb952004a4adcb7Timo Sirainen/* Like i_stream_get_data(), but read more when needed. Returns 1 if more
605eca549c08af753e05c25937bcccd66079c321Timo Sirainen than threshold bytes are available, 0 if as much or less, -1 if error or
605eca549c08af753e05c25937bcccd66079c321Timo Sirainen EOF with no bytes read that weren't already in buffer, or -2 if stream's
605eca549c08af753e05c25937bcccd66079c321Timo Sirainen input buffer is full. */
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainenint i_stream_read_data(struct istream *stream, const unsigned char **data_r,
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainen/* Append external data to input stream. Returns TRUE if successful, FALSE if
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainen there is not enough space in the stream. */
355fe8b5d02904df39e793f66da5432d86649d4aTimo Sirainenbool i_stream_add_data(struct istream *stream, const unsigned char *data,