Documents the fact that exceptional stream conditions remain set until a

client clears them.

git-svn-id: http://svn.ghostscript.com/ghostscript/trunk@2736 a1074d23-0009-0410-80fe-cf8c14f379e6

1 files changed, 9 insertions, 1 deletions

diff --git a/gs/src/scommon.h b/gs/src/scommon.h
index 3017c0767..ffa647d1e 100644
--- a/gs/src/scommon.h
+++ b/gs/src/scommon.h
@@ -35,8 +35,8 @@
 #ifndef stream_DEFINED
 #  define stream_DEFINED
 typedef struct stream_s stream;
-
 #endif
+
 /*
  * A stream_state records the state specific to a given variety of stream.
  * The buffer processing function of a stream maintains this state.
@@ -60,6 +60,14 @@ typedef struct stream_template_s stream_template;
  * we use negative values to indicate exceptional conditions.
  * (We cast these values to int explicitly, because some compilers
  * don't do this if the other arm of a conditional is a byte.)
+ *
+ * Note that when a stream reaches an exceptional condition, that condition
+ * remains set until the client does something explicit to reset it.
+ * (There should be a 'sclearerr' procedure to do that, but there isn't.)
+ * In particular, if a read stream encounters an exceptional condition,
+ * it delivers the data it has in its buffer, and then all subsequent
+ * calls to read data (sgetc, sgets, etc.) will return the exceptional
+ * condition without reading any more actual data.
  */
 /* End of data */
 #define EOFC ((int)(-1))