diff options
Diffstat (limited to 'doc/open.n')
| -rw-r--r-- | doc/open.n | 178 |
1 files changed, 65 insertions, 113 deletions
@@ -32,35 +32,23 @@ conventions described in the \fBfilename\fR manual entry. The \fIaccess\fR argument, if present, indicates the way in which the file (or command pipeline) is to be accessed. In the first form \fIaccess\fR may have any of the following values: -.TP 15 -\fBr\fR -. +.IP \fBr\fR Open the file for reading only; the file must already exist. This is the default value if \fIaccess\fR is not specified. -.TP 15 -\fBr+\fR -. +.IP \fBr+\fR Open the file for both reading and writing; the file must already exist. -.TP 15 -\fBw\fR -. +.IP \fBw\fR Open the file for writing only. Truncate it if it exists. If it does not exist, create a new file. -.TP 15 -\fBw+\fR -. +.IP \fBw+\fR Open the file for reading and writing. Truncate it if it exists. If it does not exist, create a new file. -.TP 15 -\fBa\fR -. +.IP \fBa\fR Open the file for writing only. If the file does not exist, create a new empty file. Set the file pointer to the end of the file prior to each write. -.TP 15 -\fBa+\fR -. +.IP \fBa+\fR Open the file for reading and writing. If the file does not exist, create a new empty file. Set the initial access position to the end of the file. @@ -74,44 +62,26 @@ reading or writing of binary data. In the second form, \fIaccess\fR consists of a list of any of the following flags, most of which have the standard POSIX meanings. One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. -.TP 15 -\fBRDONLY\fR -. +.IP \fBRDONLY\fR Open the file for reading only. -.TP 15 -\fBWRONLY\fR -. +.IP \fBWRONLY\fR Open the file for writing only. -.TP 15 -\fBRDWR\fR -. +.IP \fBRDWR\fR Open the file for both reading and writing. -.TP 15 -\fBAPPEND\fR -. +.IP \fBAPPEND\fR Set the file pointer to the end of the file prior to each write. -.TP 15 -\fBBINARY\fR -. +.IP \fBBINARY\fR Configure the opened channel with the \fB\-translation binary\fR option. -.TP 15 -\fBCREAT\fR -. +.IP \fBCREAT\fR Create the file if it does not already exist (without this flag it is an error for the file not to exist). -.TP 15 -\fBEXCL\fR -. +.IP \fBEXCL\fR If \fBCREAT\fR is also specified, an error is returned if the file already exists. -.TP 15 -\fBNOCTTY\fR -. +.IP \fBNOCTTY\fR If the file is a terminal device, this flag prevents the file from becoming the controlling terminal of the process. -.TP 15 -\fBNONBLOCK\fR -. +.IP \fBNONBLOCK\fR Prevents the process from blocking while opening the file, and possibly in subsequent I/O operations. The exact behavior of this flag is system- and device-dependent; its use is discouraged @@ -119,9 +89,7 @@ this flag is system- and device-dependent; its use is discouraged in nonblocking mode). For details refer to your system documentation on the \fBopen\fR system call's \fBO_NONBLOCK\fR flag. -.TP 15 -\fBTRUNC\fR -. +.IP \fBTRUNC\fR If the file exists it is truncated to zero length. .PP If a new file is created as part of opening it, \fIpermissions\fR @@ -133,6 +101,7 @@ conjunction with the process's file mode creation mask. When the file opened is an ordinary disk file, the \fBchan configure\fR and \fBfconfigure\fR commands can be used to query this additional configuration option: +.\" OPTION: -stat .TP \fB\-stat\fR . @@ -191,6 +160,7 @@ the PORTABILITY ISSUES section. The \fBchan configure\fR and \fBfconfigure\fR commands can be used to query and set additional configuration options specific to serial ports (where supported): +.\" OPTION: -mode .TP \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR . @@ -208,6 +178,7 @@ or \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. +.\" OPTION: -handshake .TP \fB\-handshake\fR \fItype\fR . @@ -226,12 +197,14 @@ There is no default handshake configuration, the initial value depends on your operating system settings. The \fB\-handshake\fR option cannot be queried. .RE +.\" OPTION: -queue .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. +.\" OPTION: -timeout .TP \fB\-timeout\fR \fImsec\fR . @@ -242,6 +215,7 @@ 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. +.\" OPTION: -ttycontrol .TP \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR . @@ -255,6 +229,7 @@ It is 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. +.\" OPTION: -ttystatus .TP \fB\-ttystatus\fR . @@ -264,6 +239,7 @@ queried. It returns the current modem status and handshake input signals 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. +.\" OPTION: -xchar .TP \fB\-xchar\fR \fI{xonChar xoffChar}\fR . @@ -271,6 +247,7 @@ The \fIsignal\fR names are returned upper case. handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. +.\" OPTION: -closemode .TP \fB\-closemode\fR \fIcloseMode\fR .VS "8.7, TIP 160" @@ -279,24 +256,19 @@ the serial channel, which defines how pending output in operating system buffers is handled when the channel is closed. The following values for \fIcloseMode\fR are supported: .RS -.TP -\fBdefault\fR -. +.IP \fBdefault\fR indicates that a system default operation should be used; all serial channels default to this. -.TP -\fBdiscard\fR -. +.IP \fBdiscard\fR indicates that the contents of the OS buffers should be discarded. Note that this is \fInot recommended\fR when writing to a POSIX terminal, as it can interact unexpectedly with handling of \fBstderr\fR. -.TP -\fBdrain\fR -. +.IP \fBdrain\fR indicates that Tcl should wait when closing the channel until all output has been consumed. This may slow down \fBclose\fR noticeably. .RE .VE "8.7, TIP 160" +.\" OPTION: -inputmode .TP \fB\-inputmode\fR \fIinputMode\fR .VS "8.7, TIP 160" @@ -306,26 +278,18 @@ the assumption that it is talking to a terminal, which controls how interactive input from users is handled. The following values for \fIinputMode\fR are supported: .RS -.TP -\fBnormal\fR -. +.IP \fBnormal\fR indicates that normal line-oriented input should be used, with standard terminal editing capabilities enabled. -.TP -\fBpassword\fR -. +.IP \fBpassword\fR indicates that non-echoing input should be used, with standard terminal editing capabilities enabled but no writing of typed characters to the terminal (except for newlines). Some terminals may indicate this specially. -.TP -\fBraw\fR -. +.IP \fBraw\fR indicates that all keyboard input should be given directly to Tcl with the terminal doing no processing at all. It does not echo the keys, leaving it up to the Tcl script to interpret what to do. -.TP -\fBreset\fR (set only) -. +.IP "\fBreset\fR (set only)" indicates that the terminal should be reset to what state it was in when the terminal was opened. .PP @@ -333,6 +297,7 @@ Note that setting this option (technically, anything that changes the terminal state from its initial value \fIvia this option\fR) will cause the channel to turn on an automatic reset of the terminal when the channel is closed. .RE +.\" OPTION: -winsize .TP \fB\-winsize\fR . @@ -340,6 +305,7 @@ turn on an automatic reset of the terminal when the channel is closed. option is query only. It retrieves a two-element list with the the current width and height of the terminal. .VE "8.7, TIP 160" +.\" OPTION: -pollinterval .TP \fB\-pollinterval\fR \fImsec\fR . @@ -349,6 +315,7 @@ 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). +.\" OPTION: -sysbuffer .TP \fB\-sysbuffer\fR \fIinSize\fR .TP @@ -359,6 +326,7 @@ 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. +.\" OPTION: -lasterror .TP \fB\-lasterror\fR . @@ -377,29 +345,29 @@ 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\fR(output) +.IP "\fBTXD\fR (output)" \fBTransmitted Data:\fR Outgoing serial data. -.IP \fBRXD\fR(input) +.IP "\fBRXD\fR (input)" \fBReceived Data:\fRIncoming serial data. -.IP \fBRTS\fR(output) +.IP "\fBRTS\fR (output)" \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\fR(input) +.IP "\fBCTS\fR (input)" \fBClear To Send:\fR The complement to RTS. Indicates that the modem is ready to receive data. -.IP \fBDTR\fR(output) +.IP "\fBDTR\fR (output)" \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\fR(input) +.IP "\fBDSR\fR (input)" \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the modem is ready to establish a link. -.IP \fBDCD\fR(input) +.IP "\fBDCD\fR (input)" \fBData Carrier Detect:\fR This line becomes active when a modem detects a .QW Carrier signal. -.IP \fBRI\fR(input) +.IP "\fBRI\fR (input)" \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 @@ -417,39 +385,27 @@ settings may be wrong. That is 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\fR \fB\-lasterror\fR may help to locate the problem. The following error codes may be returned. -.TP 10 -\fBRXOVER\fR -. +.IP \fBRXOVER\fR Windows input buffer overrun. The data comes faster than your scripts reads -it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to avoid a -temporary bottleneck and/or make your script faster. -.TP 10 -\fBTXFULL\fR -. +it or your system is overloaded. Use \fBfconfigure\fR \fB\-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. -.TP 10 -\fBOVERRUN\fR -. +.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. -.TP 10 -\fBRXPARITY\fR -. +.IP \fBRXPARITY\fR A parity error has been detected by your UART. -Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD) -may cause this error. -.TP 10 -\fBFRAME\fR -. +Wrong parity settings with \fBfconfigure\fR \fB\-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\fR \fB\-mode\fR or a noisy data line (RXD) -may cause this error. -.TP 10 -\fBBREAK\fR -. +Wrong mode settings with \fBfconfigure\fR \fB\-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). .SS "PORTABILITY ISSUES" .TP @@ -483,7 +439,7 @@ before each write, which is not an atomic operation and does not carry the guarantee of strict appending that is present on POSIX platforms. .RE .TP -\fBUnix\fR\0\0\0\0\0\0\0 +\fBUnix \fR . 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 @@ -510,6 +466,7 @@ applications on the various platforms .VS "8.7, TIP 160" On Windows only, console channels (usually \fBstdin\fR or \fBstdout\fR) support the following options: +.\" OPTION: -inputmode .TP \fB\-inputmode\fR \fIinputMode\fR . @@ -517,20 +474,14 @@ This option is used to query or change the input mode of the console channel, which controls how interactive input from users is handled. The following values for \fIinputMode\fR are supported: .RS -.TP -\fBnormal\fR -. +.IP \fBnormal\fR indicates that normal line-oriented input should be used, with standard console editing capabilities enabled. -.TP -\fBpassword\fR -. +.IP \fBpassword\fR indicates that non-echoing input should be used, with standard console -editing capabilitied enabled but no writing of typed characters to the +editing capabilities enabled but no writing of typed characters to the terminal (except for newlines). -.TP -\fBraw\fR -. +.IP \fBraw\fR indicates that all keyboard input should be given directly to Tcl with the console doing no processing at all. It does not echo the keys, leaving it up to the Tcl script to interpret what to do. @@ -544,11 +495,12 @@ Note that setting this option (technically, anything that changes the console state from its default \fIvia this option\fR) will cause the channel to turn on an automatic reset of the console when the channel is closed. .RE +.\" OPTION: -winsize .TP \fB\-winsize\fR . This option is query only. -It retrieves a two-element list with the the current width and height of the +It retrieves a two-element list with the current width and height of the console that this channel is talking to. .PP Note that the equivalent options exist on Unix, but are on the serial channel |