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 invoca-
tions 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, cre-
ate a new file.
w+ Open the file for reading and writing.
Truncate 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
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 con-
trolling terminal of the process.
NONBLOCK Prevents the process from blocking while
opening the file, and possibly in subse-
quent 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 nonblocking 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, permis-
sions (an integer) is used to set the permissions for the
new file in conjunction with the process's file mode cre-
ation mask. Permissions defaults to 0666.
COMMAND PIPELINES
If the first character of fileName is ``|'' then the
remaining characters of fileName are treated as a list of
arguments 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 pipeline is directed to the current standard out-
put unless overridden 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
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 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. |
Windows |
95 ||
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. |
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 out- |
put 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 pipeline |
does not use standard input or output, but is redi- |
rected from or to a file, then the above problems |
do not occur. |
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 actu- |
ally 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 finished executing; command pipelines run syn- |
chronously. 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 immediate end-of-file; any data the |
caller writes to the open pipe will instead be dis- |
carded. |
Since Tcl cannot be run with a real console under |
Windows 3.X, there are no interactions between com- |
mand pipelines and the console. |
Macintosh ||
Opening a command pipeline is not supported under |
Macintosh, since applications do not support the |
concept 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 read- |
ing, 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. |
See the PORTABILITY ISSUES section of the exec command for |
additional information not specific to command pipelines |
about executing applications on the various platforms |
close(n), filename(n), gets(n), read(n), puts(n), exec(n)
KEYWORDS
access mode, append, create, file, non-blocking, open,
permissions, pipeline, process