DOC: clarify some details of stream error handling

man/foreign.doc

@@ -968,15 +968,18 @@ prefixed by \textbf{S}, e.g. Sfprintf(). They differ from the C
 functions in following ways:
 \begin{itemize}
   \item Instead of returning the number of bytes written and a negative
-    value for error, they return \const{TRUE} and \const{FALSE}.
+    value for error, they return the number of characters written
+    and a negative value for error.
   \item Instead of a \ctype{FILE}, they access the Prolog streams,
     using \ctype{IOSTREAM*}. In particular, \const{Scurrent_output}
-    accesses the current output stream (similarly,
+    accesses the current output stream and works well with
+    with_output_to/2. Similarly, there are
     \const{Scurrent_intput}, \const{Suser_output},
-    \const{Suser_error}, \const{Suser_input}).
+    \const{Suser_error}, and \const{Suser_input}.
   \item If you wish to directly use the operating system's
     \const{stdin}, \const{stdout}, \const{stderr}, you can use
-    \const{Sinput}, \const{Soutput}, \const{Serror}.
+    \const{Sinput}, \const{Soutput}, \const{Serror}. These are
+    not affected by predicates such as with_output_to/2.
 \end{itemize}
 
 In general, if a stream is acquired via PL_acquire_stream(), an error

man/streams.doc

@@ -76,17 +76,25 @@ rather than a \ctype{IOSTREAM*}.
 
     \cfunction{IOSTREAM *}{PL_acquire_stream}{IOSTREAM *s}
 Obtain ownership of \arg{s} and return \arg{s}. The application must
-call PL_release_stream() when done. Only one thread can own a stream and
-this call blocks if some other thread owns the stream. Note that
-PL_get_stream() acquires ownership. This function may be called multiple
-times by the same thread (\jargon{recursive lock}).
+call PL_release_stream() when done. Only one thread can own a stream
+and this call blocks if some other thread owns the stream. This
+function may be called multiple times by the same thread
+(\jargon{recursive lock}).
+Note that PL_get_stream() also acquires ownership.
 
     \cfunction{int}{PL_release_stream}{IOSTREAM *s}
 Give up ownership acquired using PL_acquire_stream() or PL_get_stream().
 If the stream is an an error state, return \const{FALSE} with an
 exception. Otherwise return \const{TRUE}.
 \end{description}
 
+In general, stream functions do not set any Prolog error state; that
+is done by PL_release_stream(). Once a stream is in an error state,
+all subsequent functions act as no-ops (returning -1) unless
+Sclearerr() is called. If you wish to check a stream for errors, you
+can call PL_acquire_stream() followed by PL_release_stream(), which
+will return \const{FALSE} and set the Prolog exception.
+
 Below is an example that writes ``Hello World'' to a stream provided by
 Prolog. Note that PL_release_stream() raises an exception if the
 Sfprintf() failed and (thus) left the stream in an error state.
@@ -562,8 +570,17 @@ written can be more. On error, it returns a negative value; in some
 cases there is extra information (e.g., in \const{errno}) but it
 cannot be relied on.
 
+Each call to Sfprintf() is atomic in the sense that another
+thread that calls Sfprintf() on the same stream will block.
+If you wish to do a series of print statements without any
+other thread interleaving, you should call PL_acquire_stream()
+and use its returned \ctype{STREAM*} value, then call
+PL_release_stream() at the end of the print statements.
+
     \cfunction{int}{SfprintfX}{IOSTREAM *s, const char *fm, ...}
-Same as Sfprintf() but doesn't have the format-checking attribute.
+Same as Sfprintf() but doesn't have the format-checking attribute,
+which can trigger compiler warnings if the format does not match
+the arguments.
 This is intended for formats that include extended format specifiers
 such as \exam{"\%Ws"} or \exam{"\%Us"}.
 

src/SWI-Prolog.h

@@ -306,6 +306,7 @@ typedef union
 		*    DETERMINISTIC CALL/RETURN  *
 		*********************************/
 
+/* PL_succeed and PL_fail are deprecated */
 #define	PL_succeed	return TRUE	/* succeed deterministically */
 #define PL_fail		return FALSE	/* fail */