2 open - Open a file-based or command pipeline channel
7 open fileName access permissions
11 This command opens a file, serial port, or command pipeline and returns
12 a channel identifier that may be used in future invocations of commands
13 like read, puts, and close. If the first character of fileName is not
14 | then the command opens a file: fileName gives the name of the file to
15 open, and it must conform to the conventions described in the filename
18 The access argument, if present, indicates the way in which the file
19 (or command pipeline) is to be accessed. In the first form access may
20 have any of the following values:
22 r Open the file for reading only; the file must already
23 exist. This is the default value if access is not speci-
26 r+ Open the file for both reading and writing; the file
29 w Open the file for writing only. Truncate it if it
30 exists. If it doesn't exist, create a new file.
32 w+ Open the file for reading and writing. Truncate it if
33 it exists. If it doesn't exist, create a new file.
35 a Open the file for writing only. If the file doesn't
36 exist, create a new empty file. Set the file pointer to
37 the end of the file prior to each write.
39 a+ Open the file for reading and writing. If the file
40 doesn't exist, create a new empty file. Set the initial
41 access position to the end of the file.
43 In the second form, access consists of a list of any of the following
44 flags, all of which have the standard POSIX meanings. One of the flags
45 must be either RDONLY, WRONLY or RDWR.
47 RDONLY Open the file for reading only.
49 WRONLY Open the file for writing only.
51 RDWR Open the file for both reading and writing.
53 APPEND Set the file pointer to the end of the file prior to
56 CREAT Create the file if it doesn't already exist (without
57 this flag it is an error for the file not to exist).
59 EXCL If CREAT is also specified, an error is returned if the
62 NOCTTY If the file is a terminal device, this flag prevents the
63 file from becoming the controlling terminal of the
66 NONBLOCK Prevents the process from blocking while opening the
67 file, and possibly in subsequent I/O operations. The
68 exact behavior of this flag is system- and device-depen-
69 dent; its use is discouraged (it is better to use the
70 fconfigure command to put a file in nonblocking mode).
71 For details refer to your system documentation on the
72 open system call's O_NONBLOCK flag.
74 TRUNC If the file exists it is truncated to zero length.
76 If a new file is created as part of opening it, permissions (an inte-
77 ger) is used to set the permissions for the new file in conjunction
78 with the process's file mode creation mask. Permissions defaults to
81 Note that if you are going to be reading or writing binary data from
82 the channel created by this command, you should use the fconfigure com-
83 mand to change the -translation option of the channel to binary before
84 transferring any binary data. This is in contrast to the ``b'' charac-
85 ter passed as part of the equivalent of the access parameter to some
86 versions of the C library fopen() function.
90 If the first character of fileName is ``|'' then the remaining charac-
91 ters of fileName are treated as a list of arguments that describe a
92 command pipeline to invoke, in the same style as the arguments for
93 exec. In this case, the channel identifier returned by open may be
94 used to write to the command's input pipe or read from its output pipe,
95 depending on the value of access. If write-only access is used (e.g.
96 access is w), then standard output for the pipeline is directed to the
97 current standard output unless overridden by the command. If read-only
98 access is used (e.g. access is r), standard input for the pipeline is
99 taken from the current standard input unless overridden by the command.
100 The id of the spawned process is accessible through the pid command,
101 using the channel id returned by open as argument.
103 If the command (or one of the commands) executed in the command pipe-
104 line returns an error (according to the definition in exec), a Tcl
105 error is generated when close is called on the channel unless the pipe-
106 line is in non-blocking mode then no exit status is returned (a silent
107 close with -blocking 0).
109 It is often useful to use the fileevent command with pipelines so other
110 processing may happen at the same time as running the command in the
113 SERIAL COMMUNICATIONS
114 If fileName refers to a serial port, then the specified serial port is
115 opened and initialized in a platform-dependent manner. Acceptable val-
116 ues for the fileName to use to open a serial port are described in the
117 PORTABILITY ISSUES section.
119 The fconfigure command can be used to query and set additional configu-
120 ration options specific to serial ports (where supported):
122 -mode baud,parity,data,stop
123 This option is a set of 4 comma-separated values: the baud rate,
124 parity, number of data bits, and number of stop bits for this
125 serial port. The baud rate is a simple integer that specifies
126 the connection speed. Parity is one of the following letters:
127 n, o, e, m, s; respectively signifying the parity options of
128 ``none'', ``odd'', ``even'', ``mark'', or ``space''. Data is
129 the number of data bits and should be an integer from 5 to 8,
130 while stop is the number of stop bits and should be the integer
134 (Windows and Unix). This option is used to setup automatic hand-
135 shake control. Note that not all handshake types maybe supported
136 by your operating system. The type parameter is case-indepen-
139 If type is none then any handshake is switched off. rtscts
140 activates hardware handshake. Hardware handshake signals are
141 described below. For software handshake xonxoff the handshake
142 characters can be redefined with -xchar. An additional hardware
143 handshake dtrdsr is available only under Windows. There is no
144 default handshake configuration, the initial value depends on
145 your operating system settings. The -handshake option cannot be
148 -queue (Windows and Unix). The -queue option can only be queried. It
149 returns a list of two integers representing the current number
150 of bytes in the input and output queue respectively.
153 (Windows and Unix). This option is used to set the timeout for
154 blocking read operations. It specifies the maximum interval
155 between the reception of two bytes in milliseconds. For Unix
156 systems the granularity is 100 milliseconds. The -timeout
157 option does not affect write operations or nonblocking reads.
158 This option cannot be queried.
160 -ttycontrol {signal boolean signal boolean ...}
161 (Windows and Unix). This option is used to setup the handshake
162 output lines (see below) permanently or to send a BREAK over the
163 serial line. The signal names are case-independent. {RTS 1 DTR
164 0} sets the RTS output to high and the DTR output to low. The
165 BREAK condition (see below) is enabled and disabled with {BREAK
166 1} and {BREAK 0} respectively. It's not a good idea to change
167 the RTS (or DTR) signal with active hardware handshake rtscts
168 (or dtrdsr). The result is unpredictable. The -ttycontrol
169 option cannot be queried.
172 (Windows and Unix). The -ttystatus option can only be queried.
173 It returns the current modem status and handshake input signals
174 (see below). The result is a list of signal,value pairs with a
175 fixed order, e.g. {CTS 1 DSR 0 RING 1 DCD 0}. The signal names
176 are returned upper case.
178 -xchar {xonChar xoffChar}
179 (Windows and Unix). This option is used to query or change the
180 software handshake characters. Normally the operating system
181 default should be DC1 (0x11) and DC3 (0x13) representing the
182 ASCII standard XON and XOFF characters.
185 (Windows only). This option is used to set the maximum time
186 between polling for fileevents. This affects the time interval
187 between checking for events throughout the Tcl interpreter (the
188 smallest value always wins). Use this option only if you want
189 to poll the serial port more or less often than 10 msec (the
194 -sysbuffer {inSize outSize}
195 (Windows only). This option is used to change the size of Win-
196 dows system buffers for a serial channel. Especially at higher
197 communication rates the default input buffer size of 4096 bytes
198 can overrun for latent systems. The first form specifies the
199 input buffer size, in the second form both input and output
203 (Windows only). This option is query only. In case of a serial
204 communication error, read or puts returns a general Tcl file I/O
205 error. fconfigure -lasterror can be called to get a list of
206 error details. See below for an explanation of the various
211 RS-232 is the most commonly used standard electrical interface for
212 serial communications. A negative voltage (-3V..-12V) define a mark
213 (on=1) bit and a positive voltage (+3..+12V) define a space (off=0) bit
214 (RS-232C). The following signals are specified for incoming and outgo-
215 ing data, status lines and handshaking. Here we are using the terms
216 workstation for your computer and modem for the external device,
217 because some signal names (DCD, RI) come from modems. Of course your
218 external device may use these signal lines for other purposes.
222 Transmitted Data: Outgoing serial data.
225 Received Data:Incoming serial data.
228 Request To Send: This hardware handshake line informs the modem
229 that your workstation is ready to receive data. Your workstation
230 may automatically reset this signal to indicate that the input
234 Clear To Send: The complement to RTS. Indicates that the modem
235 is ready to receive data.
238 Data Terminal Ready: This signal tells the modem that the work-
239 station is ready to establish a link. DTR is often enabled auto-
240 matically whenever a serial port is opened.
243 Data Set Ready: The complement to DTR. Tells the workstation
244 that the modem is ready to establish a link.
247 Data Carrier Detect: This line becomes active when a modem
248 detects a "Carrier" signal.
251 Ring Indicator: Goes active when the modem detects an incoming
254 BREAK A BREAK condition is not a hardware signal line, but a logical
255 zero on the TXD or RXD lines for a long period of time, usually
256 250 to 500 milliseconds. Normally a receive or transmit data
257 signal stays at the mark (on=1) voltage until the next character
258 is transferred. A BREAK is sometimes used to reset the communi-
259 cations line or change the operating mode of communications
263 ERROR CODES (Windows only)
264 A lot of different errors may occur during serial read operations or
265 during event polling in background. The external device may have been
266 switched off, the data lines may be noisy, system buffers may overrun
267 or your mode settings may be wrong. That's why a reliable software
268 should always catch serial read operations. In cases of an error Tcl
269 returns a general file I/O error. Then fconfigure -lasterror may help
270 to locate the problem. The following error codes may be returned.
273 RXOVER Windows input buffer overrun. The data comes faster than your
274 scripts reads it or your system is overloaded. Use fconfigure
275 -sysbuffer to avoid a temporary bottleneck and/or make your
278 TXFULL Windows output buffer overrun. Complement to RXOVER. This
279 error should practically not happen, because Tcl cares about
280 the output buffer status.
282 OVERRUN UART buffer overrun (hardware) with data lost. The data
283 comes faster than the system driver receives it. Check your
284 advanced serial port settings to enable the FIFO (16550)
285 buffer and/or setup a lower(1) interrupt threshold value.
287 RXPARITY A parity error has been detected by your UART. Wrong parity
288 settings with fconfigure -mode or a noisy data line (RXD) may
291 FRAME A stop-bit error has been detected by your UART. Wrong mode
292 settings with fconfigure -mode or a noisy data line (RXD) may
295 BREAK A BREAK condition has been detected by your UART (see above).
299 Windows (all versions)
300 Valid values for fileName to open a serial port are of the form
301 comX:, where X is a number, generally from 1 to 4. This nota-
302 tion only works for serial ports from 1 to 9, if the system hap-
303 pens to have more than four. An attempt to open a serial port
304 that does not exist or has a number greater than 9 will fail.
305 An alternate form of opening serial ports is to use the filename
306 \\.\comX, where X is any number that corresponds to a serial
307 port; please note that this method is considerably slower on
308 Windows 95 and Windows 98.
311 When running Tcl interactively, there may be some strange inter-
312 actions between the real console, if one is present, and a com-
313 mand pipeline that uses standard input or output. If a command
314 pipeline is opened for reading, some of the lines entered at the
315 console will be sent to the command pipeline and some will be
316 sent to the Tcl evaluator. If a command pipeline is opened for
317 writing, keystrokes entered into the console are not visible
318 until the pipe is closed. This behavior occurs whether the com-
319 mand pipeline is executing 16-bit or 32-bit applications. These
320 problems only occur because both Tcl and the child application
321 are competing for the console at the same time. If the command
322 pipeline is started from a script, so that Tcl is not accessing
323 the console, or if the command pipeline does not use standard
324 input or output, but is redirected from or to a file, then the
325 above problems do not occur.
328 A command pipeline that executes a 16-bit DOS application cannot
329 be opened for both reading and writing, since 16-bit DOS appli-
330 cations that receive standard input from a pipe and send stan-
331 dard output to a pipe run synchronously. Command pipelines that
332 do not execute 16-bit DOS applications run asynchronously and
333 can be opened for both reading and writing.
335 When running Tcl interactively, there may be some strange inter-
336 actions between the real console, if one is present, and a com-
337 mand pipeline that uses standard input or output. If a command
338 pipeline is opened for reading from a 32-bit application, some
339 of the keystrokes entered at the console will be sent to the
340 command pipeline and some will be sent to the Tcl evaluator. If
341 a command pipeline is opened for writing to a 32-bit applica-
342 tion, no output is visible on the console until the pipe is
343 closed. These problems only occur because both Tcl and the
344 child application are competing for the console at the same
345 time. If the command pipeline is started from a script, so that
346 Tcl is not accessing the console, or if the command pipeline
347 does not use standard input or output, but is redirected from or
348 to a file, then the above problems do not occur.
350 Whether or not Tcl is running interactively, if a command pipe-
351 line is opened for reading from a 16-bit DOS application, the
352 call to open will not return until end-of-file has been received
353 from the command pipeline's standard output. If a command pipe-
354 line is opened for writing to a 16-bit DOS application, no data
355 will be sent to the command pipeline's standard output until the
356 pipe is actually closed. This problem occurs because 16-bit DOS
357 applications are run synchronously, as described above.
360 Opening a serial port is not currently implemented under Macin-
363 Opening a command pipeline is not supported under Macintosh,
364 since applications do not support the concept of standard input
368 Valid values for fileName to open a serial port are generally of
369 the form /dev/ttyX, where X is a or b, but the name of any
370 pseudo-file that maps to a serial port may be used. Advanced
371 configuration options are only supported for serial ports when
372 Tcl is built to use the POSIX serial interface.
374 When running Tcl interactively, there may be some strange inter-
375 actions between the console, if one is present, and a command
376 pipeline that uses standard input. If a command pipeline is
377 opened for reading, some of the lines entered at the console
378 will be sent to the command pipeline and some will be sent to
379 the Tcl evaluator. This problem only occurs because both Tcl
380 and the child application are competing for the console at the
381 same time. If the command pipeline is started from a script, so
382 that Tcl is not accessing the console, or if the command pipe-
383 line does not use standard input, but is redirected from a file,
384 then the above problem does not occur.
386 See the PORTABILITY ISSUES section of the exec command for additional
387 information not specific to command pipelines about executing applica-
388 tions on the various platforms
391 Open a command pipeline and catch any errors:
392 set fl [open "| ls this_file_does_not_exist"]
394 if {[catch {close $fl} err]} {
395 puts "ls command failed: $err"
400 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
401 puts(n), exec(n), pid(n), fopen(3)
405 access mode, append, create, file, non-blocking, open, permissions,
projects / tas-yagle.git / blob