[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 01/01: Document char-ready? limitations.
From: |
Andy Wingo |
Subject: |
[Guile-commits] 01/01: Document char-ready? limitations. |
Date: |
Mon, 20 Jun 2016 19:23:37 +0000 (UTC) |
wingo pushed a commit to branch master
in repository guile.
commit 5b6eaa91d23199f9266a3c338b8be8dcad5ecc38
Author: Andy Wingo <address@hidden>
Date: Mon Jun 20 21:21:20 2016 +0200
Document char-ready? limitations.
* doc/ref/api-io.texi (Venerable Port Interfaces): Document limitations
of char-ready?. See http://debbugs.gnu.org/10627.
---
doc/ref/api-io.texi | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 9b32c87..48ff177 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1410,6 +1410,22 @@ has been asserted by @code{char-ready?} cannot be rubbed
out.
If @code{char-ready?} were to return @code{#f} at end of file,
a port at end of file would be indistinguishable from an
interactive port that has no ready characters.
+
+Note that @code{char-ready?} only works reliably for terminals and
+sockets with one-byte encodings. Under the hood it will return
address@hidden if the port has any input buffered, or if the file descriptor
+that backs the port polls as readable, indicating that Guile can fetch
+more bytes from the kernel. However being able to fetch one byte
+doesn't mean that a full character is available; @xref{Encoding}. Also,
+on many systems it's possible for a file descriptor to poll as readable,
+but then block when it comes time to read bytes. Note also that on
+Linux kernels, all file ports backed by files always poll as readable.
+For non-file ports, this procedure always returns @code{#t}, except for
+soft ports, which have a @code{char-ready?} handler. @xref{Soft Ports}.
+
+In short, this is a legacy procedure whose semantics are hard to
+provide. However it is a useful check to see if any input is buffered.
address@hidden I/O}.
@end deffn
@rnindex read-char