summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2001-04-06 14:27:51 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2001-04-06 14:27:51 (GMT)
commitdb1db9eb0cc87f32ea08f460c71eac8b6bc1034f (patch)
treef9795f3e98f8d5a1de778ff3cc05742cb090004e
parent8bccfa351c587aaf7e5d6aa27b0ef0141806c1cf (diff)
downloadtcl-db1db9eb0cc87f32ea08f460c71eac8b6bc1034f.zip
tcl-db1db9eb0cc87f32ea08f460c71eac8b6bc1034f.tar.gz
tcl-db1db9eb0cc87f32ea08f460c71eac8b6bc1034f.tar.bz2
Improved documentation on behaviour of read w.r.t. serial ports.
[Bug #219402]
-rw-r--r--ChangeLog3
-rw-r--r--doc/read.n48
2 files changed, 36 insertions, 15 deletions
diff --git a/ChangeLog b/ChangeLog
index 8e9ac3a..09cb05e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
2001-04-06 Donal K. Fellows <fellowsd@cs.man.ac.uk>
+ * doc/read.n: Added section on "USE WITH SERIAL PORTS" to resolve
+ [Bug #219402]
+
* tests/string.test (string-2.30): Test for this case
* generic/tclCmdMZ.c (Tcl_StringObjCmd, STR_COMPARE branch): Fixed
problem caused by Utf-rep of \x00 being more than Utf-rep of \x01
diff --git a/doc/read.n b/doc/read.n
index 4194285..66dba85 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: read.n,v 1.5 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: read.n,v 1.6 2001/04/06 14:27:51 dkf Exp $
'\"
.so man.macros
.TH read n 8.1 Tcl "Tcl Built-In Commands"
@@ -22,16 +22,15 @@ read \- Read from a channel
.SH DESCRIPTION
.PP
In the first form, the \fBread\fR command reads all of the data from
-\fIchannelId\fR up to the end of the file.
-If the \fB\-nonewline\fR switch is specified then the last character
-of the file is discarded if it is a newline.
-.VS 8.1
-In the second form, the extra argument specifies how many characters to
-read. Exactly that many characters will be read and returned, unless
-there are fewer than \fInumChars\fR left in the file; in this case
-all the remaining characters are returned. If the channel is
-configured to use a multi-byte encoding, then the number of characters
-read may not be the same as the number of bytes read.
+\fIchannelId\fR up to the end of the file. If the \fB\-nonewline\fR
+switch is specified then the last character of the file is discarded
+if it is a newline. In the second form, the extra argument specifies
+how many characters to read. Exactly that many characters will be
+read and returned, unless there are fewer than \fInumChars\fR left in
+the file; in this case all the remaining characters are returned. If
+the channel is configured to use a multi-byte encoding, then the
+number of characters read may not be the same as the number of bytes
+read.
.PP
If \fIchannelId\fR is in nonblocking mode, the command may not read as
many characters as requested: once all available input has been read,
@@ -40,10 +39,8 @@ blocking for more input. If the channel is configured to use a
multi-byte encoding, then there may actually be some bytes remaining
in the internal buffers that do not form a complete character. These
bytes will not be returned until a complete character is available or
-end-of-file is reached.
-.VE 8.1
-The \fB\-nonewline\fR switch is ignored if the command returns
-before reaching the end of the file.
+end-of-file is reached. The \fB\-nonewline\fR switch is ignored if
+the command returns before reaching the end of the file.
.PP
\fBRead\fR translates end-of-line sequences in the input into
newline characters according to the \fB\-translation\fR option
@@ -51,6 +48,27 @@ for the channel.
See the \fBfconfigure\fR manual entry for a discussion on ways in
which \fBfconfigure\fR will alter input.
+.SH "USE WITH SERIAL PORTS"
+'\" Note: this advice actually applies to many versions of Tcl
+.VS 8.4
+For most applications a channel connected to a serial port should be
+configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking
+\fI0\fR. Then \fBread\fR behaves much like described above. Care
+must be taken when using \fBread\fR on blocking serial ports:
+.TP
+\fBread \fIchannelId numChars\fR
+.
+In this form \fBread\fR blocks until \fInumChars\fR have been received
+from the serial port.
+.TP
+\fBread \fIchannelId\fR
+.
+In this form \fBread\fR blocks until the reception of the end-of-file
+character, see \fBfconfigure -eofchar\fR. If there no end-of-file
+character has been configured for the channel, then \fBread\fR will
+block forever.
+.VE
+
.SH "SEE ALSO"
file(n), eof(n), fblocked(n), fconfigure(n)