summaryrefslogtreecommitdiff
path: root/doc/ref/api-io.texi
diff options
context:
space:
mode:
authorKevin Ryde <user42@zip.com.au>2005-04-29 23:45:11 +0000
committerKevin Ryde <user42@zip.com.au>2005-04-29 23:45:11 +0000
commit3fa0a042ba05be65affaa1a52109d54ace7a07b9 (patch)
tree6f1372fa40cfea90a1e366b980d02fb2181a2f16 /doc/ref/api-io.texi
parent97d790b3848e5f2c7d201b245b9c8abc8b2a4e04 (diff)
downloadguile-3fa0a042ba05be65affaa1a52109d54ace7a07b9.tar.gz
(Default Ports): Describe buffering on standard ports.
Diffstat (limited to 'doc/ref/api-io.texi')
-rw-r--r--doc/ref/api-io.texi36
1 files changed, 29 insertions, 7 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 1c3408886..4d49ec063 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -616,8 +616,19 @@ return 0 immediately if the request size is 0 bytes.
@deffnx {C Function} scm_current_input_port ()
@cindex standard input
Return the current input port. This is the default port used
-by many input procedures. Initially, @code{current-input-port}
-returns the @dfn{standard input} in Unix and C terminology.
+by many input procedures.
+
+Initially this is the @dfn{standard input} in Unix and C terminology.
+When the standard input is a tty the port is unbuffered, otherwise
+it's fully buffered.
+
+Unbuffered input is good if an application runs an interactive
+subprocess, since any type-ahead input won't go into Guile's buffer
+and hence be unavailable to the subprocess.
+
+Note that Guile buffering is completely separate from the tty ``line
+discipline''. In the usual cooked mode on a tty, Guile only sees a
+line of input once the user presses @key{return}.
@end deffn
@rnindex current-output-port
@@ -625,16 +636,27 @@ returns the @dfn{standard input} in Unix and C terminology.
@deffnx {C Function} scm_current_output_port ()
@cindex standard output
Return the current output port. This is the default port used
-by many output procedures. Initially,
-@code{current-output-port} returns the @dfn{standard output} in
-Unix and C terminology.
+by many output procedures.
+
+Initially this is the @dfn{standard output} in Unix and C terminology.
+When the standard output is a tty this port is unbuffered, otherwise
+it's fully buffered.
+
+Unbuffered output to a tty is good for ensuring progress output or a
+prompt is seen. But an application which always prints whole lines
+could change to line buffered, or an application with a lot of output
+could go fully buffered and perhaps make explicit @code{force-output}
+calls (@pxref{Writing}) at selected points.
@end deffn
@deffn {Scheme Procedure} current-error-port
@deffnx {C Function} scm_current_error_port ()
@cindex standard error output
-Return the port to which errors and warnings should be sent (the
-@dfn{standard error} in Unix and C terminology).
+Return the port to which errors and warnings should be sent.
+
+Initially this is the @dfn{standard error} in Unix and C terminology.
+When the standard error is a tty this port is unbuffered, otherwise
+it's fully buffered.
@end deffn
@deffn {Scheme Procedure} set-current-input-port port