From db1db9eb0cc87f32ea08f460c71eac8b6bc1034f Mon Sep 17 00:00:00 2001 From: dkf Date: Fri, 6 Apr 2001 14:27:51 +0000 Subject: Improved documentation on behaviour of read w.r.t. serial ports. [Bug #219402] --- ChangeLog | 3 +++ doc/read.n | 48 +++++++++++++++++++++++++++++++++--------------- 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 + * 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) -- cgit v0.12