# HG changeset patch
# User Timo Sirainen <timo.sirainen@dovecot.fi>
# Date 1467801072 -10800
# Node ID b6ae3fe5def8c1e5279d371214f58dfdf8f39155
# Parent  6be0cfc31ba0a073def43773699caf624ebeba26
lib: Updated istream's stream_errno comments.

diff -r 6be0cfc31ba0 -r b6ae3fe5def8 src/lib/istream.h
--- a/src/lib/istream.h	Wed Jul 06 13:24:03 2016 +0300
+++ b/src/lib/istream.h	Wed Jul 06 13:31:12 2016 +0300
@@ -7,7 +7,18 @@
 struct istream {
 	uoff_t v_offset;
 
+	/* Commonly used errors:
+
+	   ENOENT  - File/object doesn't exist.
+	   EPIPE   - Stream ended unexpectedly (or i_stream_close() was called).
+	   ESPIPE  - i_stream_seek() was used on a stream that can't be seeked.
+	   ENOBUFS - i_stream_read_next_line() was used for a too long line.
+	   EIO     - Internal error. Retrying may work, but it may also be
+	             because of a misconfiguration.
+	   EINVAL  - Stream is corrupted.
+	*/
 	int stream_errno;
+
 	unsigned int mmaped:1; /* be careful when copying data */
 	unsigned int blocking:1; /* read() shouldn't return 0 */
 	unsigned int closed:1;
@@ -117,7 +128,8 @@
    was successful. */
 void i_stream_skip(struct istream *stream, uoff_t count);
 /* Seek to specified position from beginning of file. Never fails, the next
-   read tells if it was successful. This works only for files. */
+   read tells if it was successful. This works only for files, others will
+   set stream_errno=ESPIPE. */
 void i_stream_seek(struct istream *stream, uoff_t v_offset);
 /* Like i_stream_seek(), but also giving a hint that after reading some data
    we could be seeking back to this mark or somewhere after it. If input