276 lines
15 KiB
HTML
276 lines
15 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - open manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="open.htm#M2" NAME="L757">NAME</A>
|
|
<DL><DD>open - Open a file-based or command pipeline channel</DL>
|
|
<DD><A HREF="open.htm#M3" NAME="L758">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>open </B><I>fileName</I>
|
|
<DD><B>open </B><I>fileName access</I>
|
|
<DD><B>open </B><I>fileName access permissions</I>
|
|
</DL>
|
|
<DD><A HREF="open.htm#M4" NAME="L759">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="open.htm#M5" NAME="L760"><B>r</B></A>
|
|
<DD><A HREF="open.htm#M6" NAME="L761"><B>r+</B></A>
|
|
<DD><A HREF="open.htm#M7" NAME="L762"><B>w</B></A>
|
|
<DD><A HREF="open.htm#M8" NAME="L763"><B>w+</B></A>
|
|
<DD><A HREF="open.htm#M9" NAME="L764"><B>a</B></A>
|
|
<DD><A HREF="open.htm#M10" NAME="L765"><B>a+</B></A>
|
|
</DL>
|
|
<DL>
|
|
<DD><A HREF="open.htm#M11" NAME="L766"><B>RDONLY</B></A>
|
|
<DD><A HREF="open.htm#M12" NAME="L767"><B>WRONLY</B></A>
|
|
<DD><A HREF="open.htm#M13" NAME="L768"><B>RDWR</B></A>
|
|
<DD><A HREF="open.htm#M14" NAME="L769"><B>APPEND</B></A>
|
|
<DD><A HREF="open.htm#M15" NAME="L770"><B>CREAT</B></A>
|
|
<DD><A HREF="open.htm#M16" NAME="L771"><B>EXCL</B></A>
|
|
<DD><A HREF="open.htm#M17" NAME="L772"><B>NOCTTY</B></A>
|
|
<DD><A HREF="open.htm#M18" NAME="L773"><B>NONBLOCK</B></A>
|
|
<DD><A HREF="open.htm#M19" NAME="L774"><B>TRUNC</B></A>
|
|
</DL>
|
|
<DD><A HREF="open.htm#M20" NAME="L775">COMMAND PIPELINES</A>
|
|
<DD><A HREF="open.htm#M21" NAME="L776">SERIAL COMMUNICATIONS</A>
|
|
<DD><A HREF="open.htm#M22" NAME="L777">CONFIGURATION OPTIONS</A>
|
|
<DL>
|
|
<DD><A HREF="open.htm#M23" NAME="L778"><B>-mode </B><I>baud</I><B>,</B><I>parity</I><B>,</B><I>data</I><B>,</B><I>stop</I></A>
|
|
<DD><A HREF="open.htm#M24" NAME="L779"><B>-pollinterval </B><I>msec</I></A>
|
|
<DD><A HREF="open.htm#M25" NAME="L780"><B>-lasterror</B></A>
|
|
</DL>
|
|
<DD><A HREF="open.htm#M26" NAME="L781">PORTABILITY ISSUES</A>
|
|
<DL>
|
|
<DD><A HREF="open.htm#M27" NAME="L782"><B>Windows </B>(all versions)</A>
|
|
<DD><A HREF="open.htm#M28" NAME="L783"><B>Windows NT</B></A>
|
|
<DD><A HREF="open.htm#M29" NAME="L784"><B>Windows 95</B></A>
|
|
<DD><A HREF="open.htm#M30" NAME="L785"><B>Macintosh</B></A>
|
|
<DD><A HREF="open.htm#M31" NAME="L786"><B>Unix</B></A>
|
|
</DL>
|
|
<DD><A HREF="open.htm#M32" NAME="L787">SEE ALSO</A>
|
|
<DD><A HREF="open.htm#M33" NAME="L788">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
open - Open a file-based or command pipeline channel
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>open </B><I>fileName</I><BR>
|
|
<B>open </B><I>fileName access</I><BR>
|
|
<B>open </B><I>fileName access permissions</I><BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command opens a file, serial port, or command pipeline and returns a
|
|
channel identifier that may be used in future invocations of commands like
|
|
<B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, and <B><A HREF="../TkCmd/close.htm">close</A></B>.
|
|
If the first character of <I>fileName</I> is not <B>|</B> then
|
|
the command opens a file:
|
|
<I>fileName</I> gives the name of the file to open, and it must conform to the
|
|
conventions described in the <B><A HREF="../TkCmd/filename.htm">filename</A></B> manual entry.
|
|
<P>
|
|
The <I>access</I> argument, if present, indicates the way in which the file
|
|
(or command pipeline) is to be accessed.
|
|
In the first form <I>access</I> may have any of the following values:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>r</B></A><DD>
|
|
Open the file for reading only; the file must already exist. This is the
|
|
default value if <I>access</I> is not specified.
|
|
<P><DT><A NAME="M6"><B>r+</B></A><DD>
|
|
Open the file for both reading and writing; the file must
|
|
already exist.
|
|
<P><DT><A NAME="M7"><B>w</B></A><DD>
|
|
Open the file for writing only. Truncate it if it exists. If it doesn't
|
|
exist, create a new file.
|
|
<P><DT><A NAME="M8"><B>w+</B></A><DD>
|
|
Open the file for reading and writing. Truncate it if it exists.
|
|
If it doesn't exist, create a new file.
|
|
<P><DT><A NAME="M9"><B>a</B></A><DD>
|
|
Open the file for writing only. If the file doesn't exist,
|
|
create a new empty file.
|
|
Set the initial access position to the end of the file.
|
|
<P><DT><A NAME="M10"><B>a+</B></A><DD>
|
|
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.
|
|
<P></DL>
|
|
<P>
|
|
In the second form, <I>access</I> 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 <B>RDONLY</B>, <B>WRONLY</B> or <B>RDWR</B>.
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M11"><B>RDONLY</B></A><DD>
|
|
Open the file for reading only.
|
|
<P><DT><A NAME="M12"><B>WRONLY</B></A><DD>
|
|
Open the file for writing only.
|
|
<P><DT><A NAME="M13"><B>RDWR</B></A><DD>
|
|
Open the file for both reading and writing.
|
|
<P><DT><A NAME="M14"><B>APPEND</B></A><DD>
|
|
Set the file pointer to the end of the file prior to each write.
|
|
<P><DT><A NAME="M15"><B>CREAT</B></A><DD>
|
|
Create the file if it doesn't already exist (without this flag it
|
|
is an error for the file not to exist).
|
|
<P><DT><A NAME="M16"><B>EXCL</B></A><DD>
|
|
If <B>CREAT</B> is also specified, an error is returned if the
|
|
file already exists.
|
|
<P><DT><A NAME="M17"><B>NOCTTY</B></A><DD>
|
|
If the file is a terminal device, this flag prevents the file from
|
|
becoming the controlling terminal of the process.
|
|
<P><DT><A NAME="M18"><B>NONBLOCK</B></A><DD>
|
|
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 <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command to put a file
|
|
in nonblocking mode).
|
|
For details refer to your system documentation on the <B>open</B> system
|
|
call's <B>O_NONBLOCK</B> flag.
|
|
<P><DT><A NAME="M19"><B>TRUNC</B></A><DD>
|
|
If the file exists it is truncated to zero length.
|
|
<P></DL>
|
|
<P>
|
|
If a new file is created as part of opening it, <I>permissions</I>
|
|
(an integer) is used to set the permissions for the new file in
|
|
conjunction with the process's file mode creation mask.
|
|
<I>Permissions</I> defaults to 0666.
|
|
<P>
|
|
Note that if you are going to be reading or writing binary data from
|
|
the channel created by this command, you should use the
|
|
<B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command to change the <B>-translation</B> option of
|
|
the channel to <B><A HREF="../TkCmd/binary.htm">binary</A></B> before transferring any binary data. This
|
|
is in contrast to the ``b'' character passed as part of the equivalent
|
|
of the <I>access</I> parameter to some versions of the C library
|
|
<I>fopen()</I> function.
|
|
<H3><A NAME="M20">COMMAND PIPELINES</A></H3>
|
|
If the first character of <I>fileName</I> is ``|'' then the
|
|
remaining characters of <I>fileName</I> are treated as a list of arguments
|
|
that describe a command pipeline to invoke, in the same style as the
|
|
arguments for <B><A HREF="../TkCmd/exec.htm">exec</A></B>.
|
|
In this case, the channel identifier returned by <B>open</B> may be used
|
|
to write to the command's input pipe or read from its output pipe,
|
|
depending on the value of <I>access</I>.
|
|
If write-only access is used (e.g. <I>access</I> is <B>w</B>), 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. <I>access</I> is <B>r</B>),
|
|
standard input for the pipeline is taken from the current standard
|
|
input unless overridden by the command.
|
|
<H3><A NAME="M21">SERIAL COMMUNICATIONS</A></H3>
|
|
If <I>fileName</I> refers to a serial port, then the specified serial port
|
|
is opened and initialized in a platform-dependent manner. Acceptable
|
|
values for the <I>fileName</I> to use to open a serial port are described in
|
|
the PORTABILITY ISSUES section.
|
|
|
|
<H3><A NAME="M22">CONFIGURATION OPTIONS</A></H3>
|
|
The <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command can be used to query and set the following
|
|
configuration option for open serial ports:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M23"><B>-mode </B><I>baud</I><B>,</B><I>parity</I><B>,</B><I>data</I><B>,</B><I>stop</I></A><DD>
|
|
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
|
|
<I>baud</I> rate is a simple integer that specifies the connection speed.
|
|
<I>Parity</I> is one of the following letters: <B>n</B>, <B>o</B>, <B>e</B>,
|
|
<B>m</B>, <B>s</B>; respectively signifying the parity options of ``none'',
|
|
``odd'', ``even'', ``mark'', or ``space''. <I>Data</I> is the number of
|
|
data bits and should be an integer from 5 to 8, while <I>stop</I> is the
|
|
number of stop bits and should be the integer 1 or 2.
|
|
<P><DT><A NAME="M24"><B>-pollinterval </B><I>msec</I></A><DD>
|
|
This option, available only on Windows for serial ports, is used to
|
|
set the maximum time between polling for fileevents. This affects the
|
|
time interval between checking for events throughout the Tcl
|
|
interpreter (the smallest value always wins). Use this option only if
|
|
you want to poll the serial port more often than 10 msec (the default).
|
|
<P><DT><A NAME="M25"><B>-lasterror</B></A><DD>
|
|
This option is available only on Windows for serial ports, and is
|
|
query only (will only be reported when directly requested).
|
|
In case of a serial communication error, <B><A HREF="../TkCmd/read.htm">read</A></B> or <B><A HREF="../TkCmd/puts.htm">puts</A></B>
|
|
returns a general Tcl file I/O error.
|
|
<B>fconfigure -lasterror</B> can be called to get a list
|
|
of error details (e.g. FRAME RXOVER).
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M26">PORTABILITY ISSUES</A></H3>
|
|
<P>
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M27"><B>Windows </B>(all versions)</A><DD>
|
|
Valid values for <I>fileName</I> to open a serial port are of the form
|
|
<B>com</B><I>X</I><B>:</B>, where <I>X</I> is a number, generally from 1 to 4.
|
|
This notation only works for serial ports from 1 to 9, if the system
|
|
happens to have more than four. An attempt to open a serial port that
|
|
does not exist or has a number greater than 9 will fail. An alternate
|
|
form of opening serial ports is to use the filename <B>\\.\comX</B>,
|
|
where X is any number that corresponds to a serial port; please note
|
|
that this method is considerably slower on Windows 95 and Windows 98.
|
|
<P><DT><A NAME="M28"><B>Windows NT</B></A><DD>
|
|
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.
|
|
<P><DT><A NAME="M29"><B>Windows 95</B></A><DD>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
Whether or not Tcl is running interactively, if a command pipeline is opened
|
|
for reading from a 16-bit DOS application, the call to <B>open</B> 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.
|
|
<P><DT><A NAME="M30"><B>Macintosh</B></A><DD>
|
|
Opening a serial port is not currently implemented under Macintosh.
|
|
<P>
|
|
Opening a command pipeline is not supported under Macintosh, since
|
|
applications do not support the concept of standard input or output.
|
|
<P><DT><A NAME="M31"><B>Unix</B></A><DD>
|
|
Valid values for <I>fileName</I> to open a serial port are generally of the
|
|
form <B>/dev/tty</B><I>X</I>, where <I>X</I> is <B>a</B> or <B>b</B>, but the name
|
|
of any pseudo-file that maps to a serial port may be used.
|
|
<P>
|
|
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.
|
|
<P></DL>
|
|
<P>
|
|
See the PORTABILITY ISSUES section of the <B><A HREF="../TkCmd/exec.htm">exec</A></B> command for additional
|
|
information not specific to command pipelines about executing
|
|
applications on the various platforms
|
|
|
|
<H3><A NAME="M32">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/file.htm">file</A></B>, <B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/filename.htm">filename</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/exec.htm">exec</A></B>, <B>fopen</B>
|
|
<H3><A NAME="M33">KEYWORDS</A></H3>
|
|
<A href="../Keywords/A.htm#access mode">access mode</A>, <A href="../Keywords/A.htm#append">append</A>, <A href="../Keywords/C.htm#create">create</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/N.htm#non-blocking">non-blocking</A>, <A href="../Keywords/O.htm#open">open</A>, <A href="../Keywords/P.htm#permissions">permissions</A>, <A href="../Keywords/P.htm#pipeline">pipeline</A>, <A href="../Keywords/P.htm#process">process</A>, <A href="../Keywords/S.htm#serial">serial</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|