Moved serial line options to their creator, open.n, from the generic page

fconfigure.n which was never an obvious spot for them. [Bug 679010]

3 files changed, 185 insertions, 203 deletions

diff --git a/ChangeLog b/ChangeLog
index dadbc40..4e8e1d7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2003-04-18  Donal K. Fellows  <fellowsd@cs.man.ac.uk>
+
+	* doc/open.n:		Moved serial port options from [fconfigure]
+	* doc/fconfigure.n:	to [open] as it is up to the creator of a
+				channel to describe the channel's special
+				config options. [Bug 679010] 
+
 2003-04-16  Don Porter  <dgp@users.sourceforge.net>
 
 	* generic/tcl.h		Made changes so that the "wideInt" Tcl_ObjType
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index da52671..d903b55 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: fconfigure.n,v 1.7 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.7.2.1 2003/04/18 00:32:34 dkf Exp $
 '\"
 .so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
@@ -203,202 +203,8 @@ If, for example, a Tcl application is started by the \fBinet\fR
 super-server common on Unix system its Tcl standard channels will be
 sockets and thus support the socket options.
 
-.VS 8.4
-.SH "SERIAL PORT CONFIGURATION OPTIONS"
-.PP
-If \fIchannelId\fR refers to a serial port, then the following
-additional configuration options are available on Windows and
-Unix systems with a POSIX serial interface:
-
-.TP
-\fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
-.
-This option is a set of 4 comma-separated values: the baud rate, parity,
-number of data bits, and number of stop bits for this serial port.  The
-\fIbaud\fR rate is a simple integer that specifies the connection speed.
-\fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
-\fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'',
-``odd'', ``even'', ``mark'', or ``space''.  \fIData\fR is the number of
-data bits and should be an integer from 5 to 8, while \fIstop\fR is the
-number of stop bits and should be the integer 1 or 2.
-
-.TP
-\fB\-handshake\fR \fItype\fR
-.
-(Windows and Unix). This option is used to setup automatic handshake
-control. Note that not all handshake types maybe supported by your operating
-system. The \fItype\fR parameter is case-independent.
-
-If \fItype\fR is \fBnone\fR then any handshake is switched off.
-\fBrtscts\fR activates hardware handshake. Hardware handshake signals
-are described below.
-For software handshake \fBxonxoff\fR the handshake characters can be redefined
-with \fB-xchar\fR.
-An additional hardware handshake \fBdtrdsr\fR is available only under Windows.
-There is no default handshake configuration, the initial value depends
-on your operating system settings.
-The \fB-handshake\fR option cannot be queried.
-
-.TP
-\fB\-queue\fR
-.
-(Windows and Unix). The \fB-queue\fR option can only be queried.
-It returns a list of two integers representing the current number
-of bytes in the input and output queue respectively.
-
-.TP
-\fB\-timeout\fR \fImsec\fR
-.
-(Windows and Unix). This option is used to set the timeout for blocking
-read operations. It specifies the maximum interval between the
-reception of two bytes in milliseconds.
-For Unix systems the granularity is 100 milliseconds.
-The \fB-timeout\fR option does not affect write operations or
-nonblocking reads.
-This option cannot be queried.
-
-.TP
-\fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR
-.
-(Windows and Unix). This option is used to setup the handshake
-output lines (see below) permanently or to send a BREAK over the serial line.
-The \fIsignal\fR names are case-independent.
-\fB{RTS 1 DTR 0}\fR sets the RTS output to high and the DTR output to low.
-The BREAK condition (see below) is enabled and disabled with \fB{BREAK 1}\fR and
-\fB{BREAK 0}\fR respectively.
-It's not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal
-with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR).
-The result is unpredictable.
-The \fB-ttycontrol\fR option cannot be queried.
-
-.TP
-\fB\-ttystatus\fR
-.
-(Windows and Unix). The \fB-ttystatus\fR option can only be
-queried.  It returns the current modem status and handshake input signals
-(see below).
-The result is a list of signal,value pairs with a fixed order,
-e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR.
-The \fIsignal\fR names are returned upper case.
-
-.TP
-\fB\-xchar\fR \fI{xonChar xoffChar}\fR
-.
-(Windows and Unix). This option is used to query or change the software
-handshake characters. Normally the operating system default should be
-DC1 (0x11) and DC3 (0x13) representing the ASCII standard
-XON and XOFF characters.
-
-.TP
-\fB\-pollinterval\fR \fImsec\fR
-.
-(Windows only). This option is used to set the maximum time between
-polling for fileevents.
-This affects the time interval between checking for events throughout the Tcl
-interpreter (the smallest value always wins).  Use this option only if
-you want to poll the serial port more or less often than 10 msec
-(the default).
-
-.TP
-\fB\-sysbuffer\fR \fIinSize\fR
-.TP
-\fB\-sysbuffer\fR \fI{inSize outSize}\fR
-.
-(Windows only). This option is used to change the size of Windows
-system buffers for a serial channel. Especially at higher communication
-rates the default input buffer size of 4096 bytes can overrun
-for latent systems. The first form specifies the input buffer size,
-in the second form both input and output buffers are defined.
-
-.TP
-\fB\-lasterror\fR
-.
-(Windows only). This option is query only.
-In case of a serial communication error, \fBread\fR or \fBputs\fR
-returns a general Tcl file I/O error.
-\fBfconfigure -lasterror\fR can be called to get a list of error details.
-See below for an explanation of the various error codes.
-
-.SH "SERIAL PORT SIGNALS"
-.PP
-RS-232 is the most commonly used standard electrical interface for serial
-communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and
-a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C).  The
-following signals are specified for incoming and outgoing data, status
-lines and handshaking. Here we are using the terms \fIworkstation\fR for
-your computer and \fImodem\fR for the external device, because some signal
-names (DCD, RI) come from modems. Of course your external device may use
-these signal lines for other purposes.
-.RS
-.IP \fBTXD(output)\fR
-\fBTransmitted Data:\fR Outgoing serial data.
-.IP \fBRXD(input)\fR
-\fBReceived Data:\fRIncoming serial data.
-.IP \fBRTS(output)\fR
-\fBRequest To Send:\fR This hardware handshake line informs the modem that
-your workstation is ready to receive data. Your workstation may
-automatically reset this signal to indicate that the input buffer is full.
-.IP \fBCTS(input)\fR
-\fBClear To Send:\fR The complement to RTS. Indicates that the modem is
-ready to receive data.
-.IP \fBDTR(output)\fR
-\fBData Terminal Ready:\fR This signal tells the modem that the workstation
-is ready to establish a link. DTR is often enabled automatically whenever a
-serial port is opened.
-.IP \fBDSR(input)\fR
-\fBData Set Ready:\fR The complement to DTR. Tells the workstation that the
-modem is ready to establish a link.
-.IP \fBDCD(input)\fR
-\fBData Carrier Detect:\fR This line becomes active when a modem detects
-a "Carrier" signal.
-.IP \fBRI(input)\fR
-\fBRing Indicator:\fR Goes active when the modem detects an incoming call.
-.IP \fBBREAK\fR
-A BREAK condition is not a hardware signal line, but a logical zero on the
-TXD or RXD lines for a long period of time, usually 250 to 500
-milliseconds.  Normally a receive or transmit data signal stays at the mark
-(on=1) voltage until the next character is transferred. A BREAK is sometimes
-used to reset the communications line or change the operating mode of
-communications hardware.
-.RE
-
-.SH "ERROR CODES (Windows only)"
-.PP
-A lot of different errors may occur during serial read operations or during
-event polling in background. The external device may have been switched
-off, the data lines may be noisy, system buffers may overrun or your mode
-settings may be wrong.  That's why a reliable software should always
-\fBcatch\fR serial read operations.  In cases of an error Tcl returns a
-general file I/O error.  Then \fBfconfigure -lasterror\fR may help to
-locate the problem.  The following error codes may be returned.
-.RS
-.IP \fBRXOVER:\fR
-Windows input buffer overrun. The data comes faster than your scripts reads
-it or your system is overloaded. Use \fBfconfigure -sysbuffer\fR to avoid a
-temporary bottleneck and/or make your script faster.
-.IP \fBTXFULL\fR
-Windows output buffer overrun. Complement to RXOVER. This error should
-practically not happen, because Tcl cares about the output buffer status.
-.IP \fBOVERRUN\fR
-UART buffer overrun (hardware) with data lost.
-The data comes faster than the system driver receives it.
-Check your advanced serial port settings to enable the FIFO (16550) buffer
-and/or setup a lower(1) interrupt threshold value.
-.IP \fBRXPARITY\fR
-A parity error has been detected by your UART.
-Wrong parity settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
-may cause this error.
-.IP \fBFRAME\fR
-A stop-bit error has been detected by your UART.
-Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
-may cause this error.
-.IP \fBBREAK\fR
-A BREAK condition has been detected by your UART (see above).
-.RE
-.VE
-
 .SH "SEE ALSO"
-close(n), flush(n), gets(n), puts(n), read(n), socket(n),
+close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
 Tcl_StandardChannels(3)
 
 .SH KEYWORDS
diff --git a/doc/open.n b/doc/open.n
index eca6607..9ef9754 100644
--- a/doc/open.n
+++ b/doc/open.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: open.n,v 1.16 2002/07/23 18:17:12 jenglish Exp $
+'\" RCS: @(#) $Id: open.n,v 1.16.2.1 2003/04/18 00:32:34 dkf Exp $
 '\" 
 .so man.macros
 .TH open n 8.3 Tcl "Tcl Built-In Commands"
@@ -142,13 +142,182 @@ values for the \fIfileName\fR to use to open a serial port are described in
 the PORTABILITY ISSUES section.
 .PP
 The \fBfconfigure\fR command can be used to query and set additional
-configuration options specific to serial ports.
+configuration options specific to serial ports (where supported):
+.TP
+\fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
+This option is a set of 4 comma-separated values: the baud rate, parity,
+number of data bits, and number of stop bits for this serial port.  The
+\fIbaud\fR rate is a simple integer that specifies the connection speed.
+\fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
+\fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'',
+``odd'', ``even'', ``mark'', or ``space''.  \fIData\fR is the number of
+data bits and should be an integer from 5 to 8, while \fIstop\fR is the
+number of stop bits and should be the integer 1 or 2.
+.TP
+\fB\-handshake\fR \fItype\fR
+(Windows and Unix). This option is used to setup automatic handshake
+control. Note that not all handshake types maybe supported by your operating
+system. The \fItype\fR parameter is case-independent.
+.sp
+If \fItype\fR is \fBnone\fR then any handshake is switched off.
+\fBrtscts\fR activates hardware handshake. Hardware handshake signals
+are described below.
+For software handshake \fBxonxoff\fR the handshake characters can be redefined
+with \fB-xchar\fR.
+An additional hardware handshake \fBdtrdsr\fR is available only under Windows.
+There is no default handshake configuration, the initial value depends
+on your operating system settings.
+The \fB-handshake\fR option cannot be queried.
+.TP
+\fB\-queue\fR
+(Windows and Unix). The \fB-queue\fR option can only be queried.
+It returns a list of two integers representing the current number
+of bytes in the input and output queue respectively.
+.TP
+\fB\-timeout\fR \fImsec\fR
+(Windows and Unix). This option is used to set the timeout for blocking
+read operations. It specifies the maximum interval between the
+reception of two bytes in milliseconds.
+For Unix systems the granularity is 100 milliseconds.
+The \fB-timeout\fR option does not affect write operations or
+nonblocking reads.
+This option cannot be queried.
+.TP
+\fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR
+(Windows and Unix). This option is used to setup the handshake
+output lines (see below) permanently or to send a BREAK over the serial line.
+The \fIsignal\fR names are case-independent.
+\fB{RTS 1 DTR 0}\fR sets the RTS output to high and the DTR output to low.
+The BREAK condition (see below) is enabled and disabled with \fB{BREAK 1}\fR and
+\fB{BREAK 0}\fR respectively.
+It's not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal
+with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR).
+The result is unpredictable.
+The \fB-ttycontrol\fR option cannot be queried.
+.TP
+\fB\-ttystatus\fR
+(Windows and Unix). The \fB-ttystatus\fR option can only be
+queried.  It returns the current modem status and handshake input signals
+(see below).
+The result is a list of signal,value pairs with a fixed order,
+e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR.
+The \fIsignal\fR names are returned upper case.
+.TP
+\fB\-xchar\fR \fI{xonChar xoffChar}\fR
+(Windows and Unix). This option is used to query or change the software
+handshake characters. Normally the operating system default should be
+DC1 (0x11) and DC3 (0x13) representing the ASCII standard
+XON and XOFF characters.
+.TP
+\fB\-pollinterval\fR \fImsec\fR
+(Windows only). This option is used to set the maximum time between
+polling for fileevents.
+This affects the time interval between checking for events throughout the Tcl
+interpreter (the smallest value always wins).  Use this option only if
+you want to poll the serial port more or less often than 10 msec
+(the default).
+.TP
+\fB\-sysbuffer\fR \fIinSize\fR
+.TP
+\fB\-sysbuffer\fR \fI{inSize outSize}\fR
+(Windows only). This option is used to change the size of Windows
+system buffers for a serial channel. Especially at higher communication
+rates the default input buffer size of 4096 bytes can overrun
+for latent systems. The first form specifies the input buffer size,
+in the second form both input and output buffers are defined.
+.TP
+\fB\-lasterror\fR
+(Windows only). This option is query only.
+In case of a serial communication error, \fBread\fR or \fBputs\fR
+returns a general Tcl file I/O error.
+\fBfconfigure -lasterror\fR can be called to get a list of error details.
+See below for an explanation of the various error codes.
+
+.SH "SERIAL PORT SIGNALS"
+.PP
+RS-232 is the most commonly used standard electrical interface for serial
+communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and
+a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C).  The
+following signals are specified for incoming and outgoing data, status
+lines and handshaking. Here we are using the terms \fIworkstation\fR for
+your computer and \fImodem\fR for the external device, because some signal
+names (DCD, RI) come from modems. Of course your external device may use
+these signal lines for other purposes.
+
+.IP \fBTXD(output)\fR
+\fBTransmitted Data:\fR Outgoing serial data.
+.IP \fBRXD(input)\fR
+\fBReceived Data:\fRIncoming serial data.
+.IP \fBRTS(output)\fR
+\fBRequest To Send:\fR This hardware handshake line informs the modem that
+your workstation is ready to receive data. Your workstation may
+automatically reset this signal to indicate that the input buffer is full.
+.IP \fBCTS(input)\fR
+\fBClear To Send:\fR The complement to RTS. Indicates that the modem is
+ready to receive data.
+.IP \fBDTR(output)\fR
+\fBData Terminal Ready:\fR This signal tells the modem that the workstation
+is ready to establish a link. DTR is often enabled automatically whenever a
+serial port is opened.
+.IP \fBDSR(input)\fR
+\fBData Set Ready:\fR The complement to DTR. Tells the workstation that the
+modem is ready to establish a link.
+.IP \fBDCD(input)\fR
+\fBData Carrier Detect:\fR This line becomes active when a modem detects
+a "Carrier" signal.
+.IP \fBRI(input)\fR
+\fBRing Indicator:\fR Goes active when the modem detects an incoming call.
+.IP \fBBREAK\fR
+A BREAK condition is not a hardware signal line, but a logical zero on the
+TXD or RXD lines for a long period of time, usually 250 to 500
+milliseconds.  Normally a receive or transmit data signal stays at the mark
+(on=1) voltage until the next character is transferred. A BREAK is sometimes
+used to reset the communications line or change the operating mode of
+communications hardware.
+
+.SH "ERROR CODES (Windows only)"
+.PP
+A lot of different errors may occur during serial read operations or during
+event polling in background. The external device may have been switched
+off, the data lines may be noisy, system buffers may overrun or your mode
+settings may be wrong.  That's why a reliable software should always
+\fBcatch\fR serial read operations.  In cases of an error Tcl returns a
+general file I/O error.  Then \fBfconfigure -lasterror\fR may help to
+locate the problem.  The following error codes may be returned.
+
+.TP 10
+\fBRXOVER\fR
+Windows input buffer overrun. The data comes faster than your scripts reads
+it or your system is overloaded. Use \fBfconfigure -sysbuffer\fR to avoid a
+temporary bottleneck and/or make your script faster.
+.TP 10
+\fBTXFULL\fR
+Windows output buffer overrun. Complement to RXOVER. This error should
+practically not happen, because Tcl cares about the output buffer status.
+.TP 10
+\fBOVERRUN\fR
+UART buffer overrun (hardware) with data lost.
+The data comes faster than the system driver receives it.
+Check your advanced serial port settings to enable the FIFO (16550) buffer
+and/or setup a lower(1) interrupt threshold value.
+.TP 10
+\fBRXPARITY\fR
+A parity error has been detected by your UART.
+Wrong parity settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
+may cause this error.
+.TP 10
+\fBFRAME\fR
+A stop-bit error has been detected by your UART.
+Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
+may cause this error.
+.TP 10
+\fBBREAK\fR
+A BREAK condition has been detected by your UART (see above).
 .VE
 
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows \fR(all versions)
-.
 Valid values for \fIfileName\fR to open a serial port are of the form
 \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4.
 This notation only works for serial ports from 1 to 9, if the system
@@ -159,7 +328,6 @@ where X is any number that corresponds to a serial port; please note
 that this method is considerably slower on Windows 95 and Windows 98.
 .TP
 \fBWindows NT\fR
-.
 When running Tcl interactively, there may be some strange interactions
 between the real console, if one is present, and a command pipeline that uses
 standard input or output.  If a command pipeline is opened for reading, some
@@ -175,7 +343,6 @@ standard input or output, but is redirected from or to a file, then the
 above problems do not occur.  
 .TP
 \fBWindows 95\fR 
-.
 A command pipeline that executes a 16-bit DOS application cannot be opened
 for both reading and writing, since 16-bit DOS applications that receive
 standard input from a pipe and send standard output to a pipe run
@@ -205,17 +372,19 @@ until the pipe is actually closed.  This problem occurs because 16-bit DOS
 applications are run synchronously, as described above.  
 .TP
 \fBMacintosh\fR
-.
 Opening a serial port is not currently implemented under Macintosh.
 .sp
 Opening a command pipeline is not supported under Macintosh, since 
 applications do not support the concept of standard input or output.
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
-.
 Valid values for \fIfileName\fR to open a serial port are generally of the
 form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name
 of any pseudo-file that maps to a serial port may be used.
+.VS 8.4
+Advanced configuration options are only supported for serial ports
+when Tcl is built to use the POSIX serial interface.
+.VE 8.4
 .sp
 When running Tcl interactively, there may be some strange interactions
 between the console, if one is present, and a command pipeline that uses