diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | doc/fconfigure.n | 198 | ||||
| -rw-r--r-- | doc/open.n | 183 |
3 files changed, 185 insertions, 203 deletions
@@ -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 @@ -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 |