2 '\" Copyright (c) 1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
11 .TH open n 7.6 Tcl "Tcl Built-In Commands"
13 '\" Note: do not modify the .SH NAME line immediately below!
15 open \- Open a file-based or command pipeline channel
18 \fBopen \fIfileName\fR
20 \fBopen \fIfileName access\fR
22 \fBopen \fIfileName access permissions\fR
28 This command opens a file, serial port, or command pipeline and returns a
30 channel identifier that may be used in future invocations of commands like
31 \fBread\fR, \fBputs\fR, and \fBclose\fR.
32 If the first character of \fIfileName\fR is not \fB|\fR then
33 the command opens a file:
34 \fIfileName\fR gives the name of the file to open, and it must conform to the
35 conventions described in the \fBfilename\fR manual entry.
37 The \fIaccess\fR argument, if present, indicates the way in which the file
38 (or command pipeline) is to be accessed.
39 In the first form \fIaccess\fR may have any of the following values:
42 Open the file for reading only; the file must already exist. This is the
43 default value if \fIaccess\fR is not specified.
46 Open the file for both reading and writing; the file must
50 Open the file for writing only. Truncate it if it exists. If it doesn't
51 exist, create a new file.
54 Open the file for reading and writing. Truncate it if it exists.
55 If it doesn't exist, create a new file.
58 Open the file for writing only. If the file doesn't exist,
59 create a new empty file.
60 Set the initial access position to the end of the file.
63 Open the file for reading and writing. If the file doesn't exist,
64 create a new empty file.
65 Set the initial access position to the end of the file.
67 In the second form, \fIaccess\fR consists of a list of any of the
68 following flags, all of which have the standard POSIX meanings.
69 One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
72 Open the file for reading only.
75 Open the file for writing only.
78 Open the file for both reading and writing.
81 Set the file pointer to the end of the file prior to each write.
84 Create the file if it doesn't already exist (without this flag it
85 is an error for the file not to exist).
88 If \fBCREAT\fR is also specified, an error is returned if the
92 If the file is a terminal device, this flag prevents the file from
93 becoming the controlling terminal of the process.
96 Prevents the process from blocking while opening the file, and
97 possibly in subsequent I/O operations. The exact behavior of
98 this flag is system- and device-dependent; its use is discouraged
99 (it is better to use the \fBfconfigure\fR command to put a file
100 in nonblocking mode).
101 For details refer to your system documentation on the \fBopen\fR system
102 call's \fBO_NONBLOCK\fR flag.
105 If the file exists it is truncated to zero length.
107 If a new file is created as part of opening it, \fIpermissions\fR
108 (an integer) is used to set the permissions for the new file in
109 conjunction with the process's file mode creation mask.
110 \fIPermissions\fR defaults to 0666.
111 .SH "COMMAND PIPELINES"
113 If the first character of \fIfileName\fR is ``|'' then the
114 remaining characters of \fIfileName\fR are treated as a list of arguments
115 that describe a command pipeline to invoke, in the same style as the
116 arguments for \fBexec\fR.
117 In this case, the channel identifier returned by \fBopen\fR may be used
118 to write to the command's input pipe or read from its output pipe,
119 depending on the value of \fIaccess\fR.
120 If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then
121 standard output for the pipeline is directed to the current standard
122 output unless overridden by the command.
123 If read-only access is used (e.g. \fIaccess\fR is \fBr\fR),
124 standard input for the pipeline is taken from the current standard
125 input unless overridden by the command.
126 .SH "SERIAL COMMUNICATIONS"
129 If \fIfileName\fR refers to a serial port, then the specified serial port
130 is opened and initialized in a platform-dependent manner. Acceptable
131 values for the \fIfileName\fR to use to open a serial port are described in
132 the PORTABILITY ISSUES section.
134 .SH "CONFIGURATION OPTIONS"
135 The \fBfconfigure\fR command can be used to query and set the following
136 configuration option for open serial ports:
138 \fB\-mode \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
140 This option is a set of 4 comma-separated values: the baud rate, parity,
141 number of data bits, and number of stop bits for this serial port. The
142 \fIbaud\fR rate is a simple integer that specifies the connection speed.
143 \fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
144 \fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'',
145 ``odd'', ``even'', ``mark'', or ``space''. \fIData\fR is the number of
146 data bits and should be an integer from 5 to 8, while \fIstop\fR is the
147 number of stop bits and should be the integer 1 or 2.
149 \fB\-pollinterval \fImsec\fR
151 This option, available only on Windows for serial ports, is used to
152 set the maximum time between polling for fileevents. This affects the
153 time interval between checking for events throughout the Tcl
154 interpreter (the smallest value always wins). Use this option only if
155 you want to poll the serial port more often than 10 msec (the default).
159 This option is available only on Windows for serial ports, and is
160 query only (will only be reported when directly requested).
161 In case of a serial communication error, \fBread\fR or \fBputs\fR
162 returns a general Tcl file I/O error.
163 \fBfconfigure -lasterror\fR can be called to get a list
164 of error details (e.g. FRAME RXOVER).
168 .SH "PORTABILITY ISSUES"
171 \fBWindows \fR(all versions)
173 Valid values for \fIfileName\fR to open a serial port are of the form
174 \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4.
175 This notation only works for serial ports from 1 to 9, if the system
176 happens to have more than four. An attempt to open a serial port that
177 does not exist or has a number greater than 9 will fail. An alternate
178 form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR,
179 where X is any number that corresponds to a serial port; please note
180 that this method is considerably slower on Windows 95 and Windows 98.
184 When running Tcl interactively, there may be some strange interactions
185 between the real console, if one is present, and a command pipeline that uses
186 standard input or output. If a command pipeline is opened for reading, some
187 of the lines entered at the console will be sent to the command pipeline and
188 some will be sent to the Tcl evaluator. If a command pipeline is opened for
189 writing, keystrokes entered into the console are not visible until the the
190 pipe is closed. This behavior occurs whether the command pipeline is
191 executing 16-bit or 32-bit applications. These problems only occur because
192 both Tcl and the child application are competing for the console at
193 the same time. If the command pipeline is started from a script, so that Tcl
194 is not accessing the console, or if the command pipeline does not use
195 standard input or output, but is redirected from or to a file, then the
196 above problems do not occur.
200 A command pipeline that executes a 16-bit DOS application cannot be opened
201 for both reading and writing, since 16-bit DOS applications that receive
202 standard input from a pipe and send standard output to a pipe run
203 synchronously. Command pipelines that do not execute 16-bit DOS
204 applications run asynchronously and can be opened for both reading and
207 When running Tcl interactively, there may be some strange interactions
208 between the real console, if one is present, and a command pipeline that uses
209 standard input or output. If a command pipeline is opened for reading from
210 a 32-bit application, some of the keystrokes entered at the console will be
211 sent to the command pipeline and some will be sent to the Tcl evaluator. If
212 a command pipeline is opened for writing to a 32-bit application, no output
213 is visible on the console until the the pipe is closed. These problems only
214 occur because both Tcl and the child application are competing for the
215 console at the same time. If the command pipeline is started from a script,
216 so that Tcl is not accessing the console, or if the command pipeline does
217 not use standard input or output, but is redirected from or to a file, then
218 the above problems do not occur.
220 Whether or not Tcl is running interactively, if a command pipeline is opened
221 for reading from a 16-bit DOS application, the call to \fBopen\fR will not
222 return until end-of-file has been received from the command pipeline's
223 standard output. If a command pipeline is opened for writing to a 16-bit DOS
224 application, no data will be sent to the command pipeline's standard output
225 until the pipe is actually closed. This problem occurs because 16-bit DOS
226 applications are run synchronously, as described above.
230 Opening a serial port is not currently implemented under Macintosh.
232 Opening a command pipeline is not supported under Macintosh, since
233 applications do not support the concept of standard input or output.
235 \fBUnix\fR\0\0\0\0\0\0\0
237 Valid values for \fIfileName\fR to open a serial port are generally of the
238 form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name
239 of any pseudo-file that maps to a serial port may be used.
241 When running Tcl interactively, there may be some strange interactions
242 between the console, if one is present, and a command pipeline that uses
243 standard input. If a command pipeline is opened for reading, some
244 of the lines entered at the console will be sent to the command pipeline and
245 some will be sent to the Tcl evaluator. This problem only occurs because
246 both Tcl and the child application are competing for the console at the
247 same time. If the command pipeline is started from a script, so that Tcl is
248 not accessing the console, or if the command pipeline does not use standard
249 input, but is redirected from a file, then the above problem does not occur.
251 See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
252 information not specific to command pipelines about executing
253 applications on the various platforms
255 close(n), filename(n), gets(n), read(n), puts(n), exec(n)
258 access mode, append, create, file, non-blocking, open, permissions,
259 pipeline, process, serial
OSDN Git Service
