diff options
Diffstat (limited to 'usr/man/mann/open.n')
| -rwxr-xr-x | usr/man/mann/open.n | 692 |
1 files changed, 692 insertions, 0 deletions
diff --git a/usr/man/mann/open.n b/usr/man/mann/open.n new file mode 100755 index 000000000..173d62816 --- /dev/null +++ b/usr/man/mann/open.n @@ -0,0 +1,692 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. +.TH open n 8.3 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +open \- Open a file-based or command pipeline channel +.SH SYNOPSIS +.sp +\fBopen \fIfileName\fR +.br +\fBopen \fIfileName access\fR +.br +\fBopen \fIfileName access permissions\fR +.BE +.SH DESCRIPTION +.PP +This command opens a file, serial port, or command pipeline and returns a +channel identifier that may be used in future invocations of commands like +\fBread\fR, \fBputs\fR, and \fBclose\fR. +If the first character of \fIfileName\fR is not \fB|\fR then +the command opens a file: +\fIfileName\fR gives the name of the file to open, and it must conform to the +conventions described in the \fBfilename\fR manual entry. +.PP +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 +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 +Open the file for both reading and writing; the file must +already exist. +.TP 15 +\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 +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 +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 +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. +.VS 8.5 +.PP +All of the legal \fIaccess\fR values above may have the character +\fBb\fR added as the second or third character in the value to +indicate that the opened channel should be configured with the +\fB\-translation binary\fR option, making the channel suitable for +reading or writing of binary data. +.VE 8.5 +.PP +In the second form, \fIaccess\fR consists of a list of any of the +following flags, all 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 +Open the file for reading only. +.TP 15 +\fBWRONLY\fR +Open the file for writing only. +.TP 15 +\fBRDWR\fR +Open the file for both reading and writing. +.TP 15 +\fBAPPEND\fR +Set the file pointer to the end of the file prior to each write. +.VS 8.5 +.TP 15 +\fBBINARY\fR +Configure the opened channel with the \fB\-translation binary\fR option. +.VE 8.5 +.TP 15 +\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 +If \fBCREAT\fR is also specified, an error is returned if the +file already exists. +.TP 15 +\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 +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 +(it is better to use the \fBfconfigure\fR command to put a file +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 +If the file exists it is truncated to zero length. +.PP +If a new file is created as part of opening it, \fIpermissions\fR +(an integer) is used to set the permissions for the new file in +conjunction with the process's file mode creation mask. +\fIPermissions\fR defaults to 0666. +.SH "COMMAND PIPELINES" +.PP +If the first character of \fIfileName\fR is +.QW | +then the +remaining characters of \fIfileName\fR are treated as a list of arguments +that describe a command pipeline to invoke, in the same style as the +arguments for \fBexec\fR. +In this case, the channel identifier returned by \fBopen\fR may be used +to write to the command's input pipe or read from its output pipe, +depending on the value of \fIaccess\fR. +If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then +standard output for the pipeline is directed to the current standard +output unless overridden by the command. +If read-only access is used (e.g. \fIaccess\fR is \fBr\fR), +standard input for the pipeline is taken from the current standard +input unless overridden by the command. +The id of the spawned process is accessible through the \fBpid\fR +command, using the channel id returned by \fBopen\fR as argument. +.PP +If the command (or one of the commands) executed in the command +pipeline returns an error (according to the definition in \fBexec\fR), +a Tcl error is generated when \fBclose\fR is called on the channel +unless the pipeline is in non-blocking mode then no exit status is +returned (a silent \fBclose\fR with -blocking 0). +.PP +It is often useful to use the \fBfileevent\fR command with pipelines +so other processing may happen at the same time as running the command +in the background. +.SH "SERIAL COMMUNICATIONS" +.PP +If \fIfileName\fR refers to a serial port, then the specified serial port +is opened and initialized in a platform-dependent manner. Acceptable +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 (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 +.QW none , +.QW odd , +.QW even , +.QW mark , +or +.QW 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. +.RS +.PP +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. +.RE +.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 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. +.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 +.QW 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 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 -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). +.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 +happens to have more than four. An attempt to open a serial port that +does not exist or has a number greater than 9 will fail. An alternate +form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR, +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 +of the lines entered at the console will be sent to the command pipeline and +some will be sent to the Tcl evaluator. If a command pipeline is opened for +writing, keystrokes entered into the console are not visible until the +pipe is closed. This behavior occurs whether the command pipeline is +executing 16-bit or 32-bit applications. These problems only occur because +both Tcl and the child application are competing for the console at +the same time. If the command pipeline is started from a script, so that Tcl +is not accessing the console, or if the command pipeline does not use +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 +synchronously. Command pipelines that do not execute 16-bit DOS +applications run asynchronously and can be opened for both reading and +writing. +.RS +.PP +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 from +a 32-bit application, some of the keystrokes entered at the console will be +sent to the command pipeline and some will be sent to the Tcl evaluator. If +a command pipeline is opened for writing to a 32-bit application, no output +is visible on the console until the pipe is closed. These problems only +occur because both Tcl and the child application are competing for the +console at the same time. If the command pipeline is started from a script, +so that Tcl is not accessing the console, or if the command pipeline does +not use standard input or output, but is redirected from or to a file, then +the above problems do not occur. +.PP +Whether or not Tcl is running interactively, if a command pipeline is opened +for reading from a 16-bit DOS application, the call to \fBopen\fR will not +return until end-of-file has been received from the command pipeline's +standard output. If a command pipeline is opened for writing to a 16-bit DOS +application, no data will be sent to the command pipeline's standard output +until the pipe is actually closed. This problem occurs because 16-bit DOS +applications are run synchronously, as described above. +.RE +.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. +Advanced configuration options are only supported for serial ports +when Tcl is built to use the POSIX serial interface. +.RS +.PP +When running Tcl interactively, there may be some strange interactions +between the console, if one is present, and a command pipeline that uses +standard input. If a command pipeline is opened for reading, some +of the lines entered at the console will be sent to the command pipeline and +some will be sent to the Tcl evaluator. This problem only occurs because +both Tcl and the child application are competing for the console at the +same time. If the command pipeline is started from a script, so that Tcl is +not accessing the console, or if the command pipeline does not use standard +input, but is redirected from a file, then the above problem does not occur. +.RE +.PP +See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for +additional information not specific to command pipelines about executing +applications on the various platforms +.SH "EXAMPLE" +Open a command pipeline and catch any errors: +.CS +set fl [\fBopen\fR "| ls this_file_does_not_exist"] +set data [read $fl] +if {[catch {close $fl} err]} { + puts "ls command failed: $err" +} +.CE +.SH "SEE ALSO" +file(n), close(n), filename(n), fconfigure(n), gets(n), read(n), +puts(n), exec(n), pid(n), fopen(3) +.SH KEYWORDS +access mode, append, create, file, non-blocking, open, permissions, +pipeline, process, serial |