Initial revision

1 files changed, 249 insertions, 0 deletions

diff --git a/doc/open.n b/doc/open.n
new file mode 100644
index 0000000..feb7b61
--- /dev/null
+++ b/doc/open.n
@@ -0,0 +1,249 @@
+'\"
+'\" 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