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