Introducing persistent error state on streams.

* lib.c (cobj_ops): New function.

* lib.h (cobj_ops): Declared.

* stream.c (null_ops): Initializer updated.
(struct stdio_handle): New member, err.
(stdio_stream_mark): Mark the err member.
(errno_to_string): New static function.
(stdio_maybe_read_error, stdio_maybe_error): Set persistent error
state. Use errno_to_string_function.
(stdio_put_string, stdio_put_char, stdio_put_byte, stdio_seek,
stdio_get_line): Set errno to zero, so that if the underlying
operations do not set errno on err, we don't misinterpret some pervious
errno value as pertaining to the failed stream operation.
(stdio_get_error, stdio_get_error_str, stdio_clear_error): New static
functions.
(stdio_ops, tail_ops, pipe_ops): Update initializer with new functions.
(string_in_get_error, string_in_get_error_str): New static functions.
(string_in_ops): Update initializer with new functions.
(byte_in_get_error, byte_in_get_error_str): New static functions.
(byte_in_ops): Update initializer with new functions.
(string_out_ops, strlist_out_ops): Update initializer with null
pointers for new functions.
(struct dir_handle): New struct type.
(dir_destroy, dir_mark): New functions.
(dir_get_line): Refactor for struct dir_handle context rather than DIR.
Persist error state.
(dir_close): Refactor for struct dir_handle.
(dir_get_error, dir_get_error_str, dir_clear_error): New static functions.
(dir_ops): Update initializer with new functions.
(make_stdio_stream_common): Initialize new err member.
(make_dir_stream): Refactor for struct dir_handle.
(get_error, get_error_str, clear_error): New functions.
(cat_get_error, cat_get_error_str, cat_clear_error): New static
functions.
(cat_stream_ops): Update initializer with new functions.
(stream_init): Register get-error, get-error-str, clear-error intrinsics.

* stream.h (struct strm_ops): New function pointer members, get_error,
get_error_str and clear_error.
(strm_ops_init): Macro extended with new arguments for new function pointers.
(get_error, get_error_str, clear_error): Declared.

* syslog.c (syslog_strm_ops): Update initializer with null
pointers for new functions.

* txr.1: Documented get-error, get-error-str and clear-error.

1 files changed, 58 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index e0b86ebf..5c4d61c6 100644
--- a/txr.1
+++ b/txr.1
@@ -22386,6 +22386,64 @@ function throws an exception if an error occurs during the close operation
 instead of returning
 .codn nil .
 
+.coNP Functions @, get-error @ get-error-str and @ clear-error
+.synb
+.mets (get-error < stream )
+.mets (get-error-str < stream )
+.mets (clear-error < stream )
+.syne
+.desc
+When a stream operation fails, the
+.code get-error
+and
+.code get-error-str
+functions may be used to inquire about a more detailed cause of the error.
+
+Not all streams support these functions to the same extent. For instance,
+string input streams have no persistent state. The only error which occurs
+is the condition when the string has no more data.
+
+The
+.code get-error
+inquires
+.meta stream
+about its error condition.
+
+The function returns
+.code nil
+to indicate there is no error condition,
+.code t
+to indicate an end-of-data condition,
+or else a value which is specific to the stream type indicating the
+specific error type.
+
+Note: for some streams, it is possible for the
+.code t
+value to be returned even though no operation has failed; that is to say, the
+streams "know" they are at the end of the data even though no read operation
+has failed. Code which depends on this will not work with streams which
+do not thus indicate the end-of-data
+.I a priori,
+but by means of a read operation which fails.
+
+The
+.code get-error-str
+function returns a text representation of the error code. The
+.code nil
+error code is represented as the string
+.codn "no error" ;
+the
+.code t
+error code as
+.code "eof"
+and other codes have a stream-specific representation.
+
+The
+.code clear-error
+function removes the error situation from a stream. On some streams, it does
+nothing. If an error has occurred on a stream, this function should be called
+prior to re-trying any I/O or positioning operations.
+
 .coNP Functions @, get-line @ get-char and @ get-byte
 .synb
 .mets (get-line <> [ stream ])