tcl7.6 User Commands - open
NAME
open - Open a file-based or command pipeline channel
SYNOPSIS
open fileName
open fileName access
open fileName access permissions
DESCRIPTION
This command opens a file or command pipeline and returns a
channel identifier that may be used in future invocations of
commands like read, puts, and close. If the first character
of fileName is not | then the command opens a file:
fileName gives the name of the file to open, and it must
conform to the conventions described in the filename manual
entry.
The access argument, if present, indicates the way in which
the file (or command pipeline) is to be accessed. In the
first form access may have any of the following values:
r Open the file for reading only; the file must
already exist. This is the default value if
access is not specified.
r+ Open the file for both reading and writing;
the file must already exist.
w Open the file for writing only. Truncate it
if it exists. If it doesn't exist, create a
new file.
w+ Open the file for reading and writing. Trun-
cate it if it exists. If it doesn't exist,
create a new file.
a Open the file for writing only. The file
must already exist, and the file is posi-
tioned so that new data is appended to the
file.
a+ Open the file for reading and writing. If
the file doesn't exist, create a new empty
file. Set the initial access position to
the end of the file.
In the second form, access 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 RDONLY, WRONLY or
RDWR.
RDONLY Open the file for reading only.
WRONLY Open the file for writing only.
RDWR Open the file for both reading and writing.
APPEND Set the file pointer to the end of the file
prior to each write.
CREAT Create the file if it doesn't already exist
(without this flag it is an error for the
file not to exist).
EXCL If CREAT is also specified, an error is
returned if the file already exists.
NOCTTY If the file is a terminal device, this flag
prevents the file from becoming the control-
ling terminal of the process.
NONBLOCK 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
fconfigure command to put a file in nonblock-
ing mode). For details refer to your system
documentation on the open system call's
O_NONBLOCK flag.
TRUNC If the file exists it is truncated to zero
length.
If a new file is created as part of opening it, permissions
(an integer) is used to set the permissions for the new file
in conjunction with the process's file mode creation mask.
Permissions defaults to 0666.
COMMAND PIPELINES
If the first character of fileName is ``|'' then the remain-
ing characters of fileName are treated as a list of argu-
ments that describe a command pipeline to invoke, in the
same style as the arguments for exec. In this case, the
channel identifier returned by open may be used to write to
the command's input pipe or read from its output pipe,
depending on the value of access. If write-only access is
used (e.g. access is w), then standard output for the pipe-
line is directed to the current standard output unless over-
ridden by the command. If read-only access is used (e.g.
access is r), standard input for the pipeline is taken from
the current standard input unless overridden by the command.
PORTABILITY ISSUES |
Windows NT |
| |
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 the pipe is closed. This |
behavior occurs whether the command pipeline is execut- |
ing 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 pipe- |
line does not use standard input or output, but is |
redirected from or to a file, then the above problems |
do not occur. |
Win- |
dows 95 |
| |
A command pipeline that executes a 16-bit DOS applica- |
tion 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 exe- |
cute 16-bit DOS applications run asynchronously and can |
be opened for both reading and writing. |
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 keys- |
trokes entered at the console will be sent to the com- |
mand pipeline and some will be sent to the Tcl evalua- |
tor. If a command pipeline is opened for writing to a |
32-bit application, no output is visible on the console |
until the 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 pipe- |
line does not use standard input or output, but is |
redirected from or to a file, then the above problems |
do not occur. |
Whether or not Tcl is running interactively, if a com- |
mand pipeline is opened for reading from a 16-bit DOS |
application, the call to open 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. |
Windows 3.X |
| |
A command pipeline can execute 16-bit or 32-bit DOS or |
Windows applications, but the call to open will not |
return until the last program in the pipeline has fin- |
ished executing; command pipelines run synchronously. |
If the pipeline is opened with write access (either |
just writing or both reading and writing) the first |
application in the pipeline will instead see an immedi- |
ate end-of-file; any data the caller writes to the open |
pipe will instead be discarded. |
Since Tcl cannot be run with a real console under Win- |
dows 3.X, there are no interactions between command |
pipelines and the console. |
Macin- |
tosh |
| |
Opening a command pipeline is not supported under |
Macintosh, since applications do not support the con- |
cept of standard input or output. |
Unix |
| |
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 stan- |
dard input, but is redirected from a file, then the |
above problem does not occur. |
See the PORTABILITY ISSUES section of the exec command for |
additional information not specific to command pipelines |
about executing applications on the various platforms |
SEE ALSO |
close(n), filename(n), gets(n), read(n), puts(n), exec(n)
KEYWORDS
access mode, append, create, file, non-blocking, open, per-
missions, pipeline, process