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