250 lines
10 KiB
Plaintext
250 lines
10 KiB
Plaintext
'\"
|
|
'\" 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.
|
|
'\"
|
|
'\" SCCS: @(#) open.n 1.16 97/01/14 18:00:35
|
|
'\"
|
|
.so man.macros
|
|
.TH open n 7.6 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
|
|
.VS
|
|
This command opens a file, serial port, or command pipeline and returns a
|
|
.VE
|
|
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 doesn't
|
|
exist, create a new file.
|
|
.TP 15
|
|
\fBw+\fR
|
|
Open the file for reading and writing. Truncate it if it exists.
|
|
If it doesn't exist, create a new file.
|
|
.TP 15
|
|
\fBa\fR
|
|
Open the file for writing only. The file must already exist, and the file
|
|
is positioned so that new data is appended to the file.
|
|
.TP 15
|
|
\fBa+\fR
|
|
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.
|
|
.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.
|
|
.TP 15
|
|
\fBCREAT\fR
|
|
Create the file if it doesn't 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 ``|'' 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.
|
|
.SH "SERIAL COMMUNICATIONS"
|
|
.VS
|
|
.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.
|
|
|
|
.SH "CONFIGURATION OPTIONS"
|
|
The \fBfconfigure\fR command can be used to query and set the following
|
|
configuration option for open serial ports:
|
|
.TP
|
|
\fB\-mode \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 ``none'',
|
|
``odd'', ``even'', ``mark'', or ``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.
|
|
.VE
|
|
|
|
.VS
|
|
.SH "PORTABILITY ISSUES"
|
|
.sp
|
|
.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. An
|
|
attempt to open a serial port that does not exist will fail.
|
|
.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 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.
|
|
.sp
|
|
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 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.
|
|
.sp
|
|
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.
|
|
.TP
|
|
\fBWindows 3.X\fR
|
|
.
|
|
A command pipeline can execute 16-bit or 32-bit DOS or Windows
|
|
applications, but the call to \fBopen\fR will not return until the last
|
|
program in the pipeline has finished 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 immediate end-of-file; any data the caller
|
|
writes to the open pipe will instead be discarded.
|
|
.sp
|
|
Since Tcl cannot be run with a real console under Windows 3.X, there are
|
|
no interactions between command pipelines and the console.
|
|
.TP
|
|
\fBMacintosh\fR
|
|
.
|
|
Opening a serial port is not currently implemented under Macintosh.
|
|
.sp
|
|
Opening a command pipeline is not supported under Macintosh, since
|
|
applications do not support the concept of standard input or output.
|
|
.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.
|
|
.sp
|
|
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.
|
|
.LP
|
|
See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
|
|
information not specific to command pipelines about executing
|
|
applications on the various platforms
|
|
.SH "SEE ALSO"
|
|
close(n), filename(n), gets(n), read(n), puts(n), exec(n)
|
|
.VE
|
|
.SH KEYWORDS
|
|
access mode, append, create, file, non-blocking, open, permissions,
|
|
pipeline, process, serial
|