1mNAME0m
       open - Open a file-based or command pipeline channel

1mSYNOPSIS0m
       1mopen 4m22mfileName0m
       1mopen 4m22mfileName24m 4maccess0m
       1mopen 4m22mfileName24m 4maccess24m 4mpermissions0m


1mDESCRIPTION0m
       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  1mread22m, 1mputs22m, and 1mclose22m.  If the first character of 4mfileName24m is not
       1m| 22mthen the command opens a file: 4mfileName24m gives the name of the file to
       open,  and it must conform to the conventions described in the 1mfilename0m
       manual entry.

       The 4maccess24m argument, if present, indicates the way in  which  the  file
       (or  command pipeline) is to be accessed.  In the first form 4maccess24m may
       have any of the following values:

       1mr              22mOpen the file for reading only; the  file  must  already
                      exist. This is the default value if 4maccess24m is not speci-
                      fied.

       1mr+             22mOpen the file for both reading  and  writing;  the  file
                      must already exist.

       1mw              22mOpen  the  file  for  writing  only.   Truncate it if it
                      exists.  If it doesn't exist, create a new file.

       1mw+             22mOpen the file for reading and writing.  Truncate  it  if
                      it exists.  If it doesn't exist, create a new file.

       1ma              22mOpen  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.

       1ma+             22mOpen  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, 4maccess24m 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 1mRDONLY22m, 1mWRONLY 22mor 1mRDWR22m.

       1mRDONLY         22mOpen the file for reading only.

       1mWRONLY         22mOpen the file for writing only.

       1mRDWR           22mOpen the file for both reading and writing.

       1mAPPEND         22mSet  the  file  pointer  to the end of the file prior to
                      each write.

       1mCREAT          22mCreate the file if it  doesn't  already  exist  (without
                      this flag it is an error for the file not to exist).

       1mEXCL           22mIf  1mCREAT 22mis also specified, an error is returned if the
                      file already exists.

       1mNOCTTY         22mIf the file is a terminal device, this flag prevents the
                      file  from  becoming  the  controlling  terminal  of the
                      process.

       1mNONBLOCK       22mPrevents 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-depen-
                      dent;   its  use is discouraged (it is better to use the
                      1mfconfigure 22mcommand to put a file in  nonblocking  mode).
                      For  details  refer  to your system documentation on the
                      1mopen 22msystem call's 1mO_NONBLOCK 22mflag.

       1mTRUNC          22mIf the file exists it is truncated to zero length.

       If a new file is created as part of opening it, 4mpermissions24m  (an  inte-
       ger)  is  used  to  set the permissions for the new file in conjunction
       with the process's file mode creation mask.   4mPermissions24m  defaults  to
       0666.

       Note  that  if  you are going to be reading or writing binary data from
       the channel created by this command, you should use the 1mfconfigure 22mcom-
       mand  to change the 1m-translation 22moption of the channel to 1mbinary 22mbefore
       transferring any binary data.  This is in contrast to the ``b'' charac-
       ter  passed  as  part of the equivalent of the 4maccess24m parameter to some
       versions of the C library 4mfopen()24m function.


1mCOMMAND PIPELINES0m
       If the first character of 4mfileName24m is ``|'' then the remaining  charac-
       ters  of  4mfileName24m  are  treated as a list of arguments that describe a
       command pipeline to invoke, in the same  style  as  the  arguments  for
       1mexec22m.   In  this  case,  the channel identifier returned by 1mopen 22mmay be
       used to write to the command's input pipe or read from its output pipe,
       depending  on  the value of 4maccess24m.  If write-only access is used (e.g.
       4maccess24m is 1mw22m), 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. 4maccess24m is 1mr22m), standard input for the  pipeline  is
       taken from the current standard input unless overridden by the command.
       The id of the spawned process is accessible through  the  1mpid  22mcommand,
       using the channel id returned by 1mopen 22mas argument.

       If  the  command (or one of the commands) executed in the command pipe-
       line returns an error (according to the  definition  in  1mexec22m),  a  Tcl
       error  is generated when 1mclose 22mis called on the channel (similar to the
       1mclose 22mcommand.)

       It is often useful to use the 1mfileevent 22mcommand with pipelines so other
       processing  may  happen  at the same time as running the command in the
       background.

1mSERIAL COMMUNICATIONS0m
       If 4mfileName24m refers to a serial port, then the specified serial port  is
       opened and initialized in a platform-dependent manner.  Acceptable val-
       ues for the 4mfileName24m to use to open a serial port are described in  the
       PORTABILITY ISSUES section.

       The 1mfconfigure 22mcommand can be used to query and set additional configu-
       ration options specific to serial ports (where supported):

       1m-mode 4m22mbaud24m1m,4m22mparity24m1m,4m22mdata24m1m,4m22mstop0m
              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 4mbaud24m rate is a simple integer  that  specifies
              the  connection  speed.  4mParity24m is one of the following letters:
              1mn22m, 1mo22m, 1me22m, 1mm22m, 1ms22m; respectively signifying  the  parity  options  of
              ``none'',  ``odd'',  ``even'',  ``mark'', or ``space''.  4mData24m is
              the number of data bits and should be an integer from  5  to  8,
              while  4mstop24m is the number of stop bits and should be the integer
              1 or 2.

       1m-handshake 4m22mtype0m
              (Windows and Unix). This option is used to setup automatic hand-
              shake control. Note that not all handshake types maybe supported
              by your operating system. The 4mtype24m  parameter  is  case-indepen-
              dent.

              If  4mtype24m  is  1mnone  22mthen  any handshake is switched off.  1mrtscts0m
              activates hardware handshake.  Hardware  handshake  signals  are
              described  below.   For software handshake 1mxonxoff 22mthe handshake
              characters can be redefined with 1m-xchar22m.  An additional hardware
              handshake  1mdtrdsr  22mis available only under Windows.  There is no
              default handshake configuration, the initial  value  depends  on
              your operating system settings.  The 1m-handshake 22moption cannot be
              queried.

       1m-queue 22m(Windows and Unix). The 1m-queue 22moption can only be  queried.   It
              returns  a  list of two integers representing the current number
              of bytes in the input and output queue respectively.

       1m-timeout 4m22mmsec0m
              (Windows and Unix). This option is used to set the  timeout  for
              blocking  read  operations.  It  specifies  the maximum interval
              between the reception of two bytes in  milliseconds.   For  Unix
              systems  the  granularity  is  100  milliseconds.   The 1m-timeout0m
              option does not affect write operations  or  nonblocking  reads.
              This option cannot be queried.

       1m-ttycontrol 4m22m{signal24m 4mboolean24m 4msignal24m 4mboolean24m 4m...}0m
              (Windows  and  Unix). This option is used to setup the handshake
              output lines (see below) permanently or to send a BREAK over the
              serial line.  The 4msignal24m names are case-independent.  1m{RTS 1 DTR0m
              1m0} 22msets the RTS output to high and the DTR output to  low.   The
              BREAK  condition (see below) is enabled and disabled with 1m{BREAK0m
              1m1} 22mand 1m{BREAK 0} 22mrespectively.  It's not a good idea  to  change
              the  1mRTS  22m(or  1mDTR22m) signal with active hardware handshake 1mrtscts0m
              (or 1mdtrdsr22m).  The  result  is  unpredictable.   The  1m-ttycontrol0m
              option cannot be queried.

       1m-ttystatus0m
              (Windows  and  Unix). The 1m-ttystatus 22moption can only be queried.
              It returns the current modem status and handshake input  signals
              (see  below).  The result is a list of signal,value pairs with a
              fixed order, e.g. 1m{CTS 1 DSR 0 RING 1 DCD 0}22m.  The 4msignal24m  names
              are returned upper case.

       1m-xchar 4m22m{xonChar24m 4mxoffChar}0m
              (Windows  and  Unix). This option is used to query or change the
              software handshake characters.  Normally  the  operating  system
              default  should  be  DC1  (0x11) and DC3 (0x13) representing the
              ASCII standard XON and XOFF characters.

       1m-pollinterval 4m22mmsec0m
              (Windows only). This option 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 or less often  than  10  msec  (the
              default).

       1m-sysbuffer 4m22minSize0m

       1m-sysbuffer 4m22m{inSize24m 4moutSize}0m
              (Windows  only).  This option is used to change the size of Win-
              dows system buffers for a serial channel. Especially  at  higher
              communication  rates the default input buffer size of 4096 bytes
              can overrun for latent systems. The  first  form  specifies  the
              input  buffer  size,  in  the  second form both input and output
              buffers are defined.

       1m-lasterror0m
              (Windows only). This option is query only.  In case of a  serial
              communication error, 1mread 22mor 1mputs 22mreturns a general Tcl file I/O
              error.  1mfconfigure -lasterror 22mcan be called to  get  a  list  of
              error  details.   See  below  for  an explanation of the various
              error codes.


1mSERIAL PORT SIGNALS0m
       RS-232 is the most commonly  used  standard  electrical  interface  for
       serial  communications.  A  negative  voltage (-3V..-12V) define a mark
       (on=1) bit and a positive voltage (+3..+12V) define a space (off=0) bit
       (RS-232C).  The following signals are specified for incoming and outgo-
       ing data, status lines and handshaking. Here we  are  using  the  terms
       4mworkstation24m  for  your  computer  and  4mmodem24m  for  the external device,
       because some signal names (DCD, RI) come from modems.  Of  course  your
       external device may use these signal lines for other purposes.


       1mTXD(output)0m
              1mTransmitted Data: 22mOutgoing serial data.

       1mRXD(input)0m
              1mReceived Data:22mIncoming serial data.

       1mRTS(output)0m
              1mRequest  To Send: 22mThis hardware handshake line informs the modem
              that your workstation is ready to receive data. Your workstation
              may  automatically  reset this signal to indicate that the input
              buffer is full.

       1mCTS(input)0m
              1mClear To Send: 22mThe complement to RTS. Indicates that  the  modem
              is ready to receive data.

       1mDTR(output)0m
              1mData  Terminal Ready: 22mThis signal tells the modem that the work-
              station is ready to establish a link. DTR is often enabled auto-
              matically whenever a serial port is opened.

       1mDSR(input)0m
              1mData  Set  Ready:  22mThe  complement to DTR. Tells the workstation
              that the modem is ready to establish a link.

       1mDCD(input)0m
              1mData Carrier Detect: 22mThis  line  becomes  active  when  a  modem
              detects a "Carrier" signal.

       1mRI(input)0m
              1mRing  Indicator:  22mGoes active when the modem detects an incoming
              call.

       1mBREAK  22mA BREAK condition is not a hardware signal line, but  a  logical
              zero  on the TXD or RXD lines for a long period of time, usually
              250 to 500 milliseconds.  Normally a receive  or  transmit  data
              signal stays at the mark (on=1) voltage until the next character
              is transferred. A BREAK is sometimes used to reset the  communi-
              cations  line  or  change  the  operating mode of communications
              hardware.


1mERROR CODES (Windows only)0m
       A lot of different errors may occur during serial  read  operations  or
       during  event  polling in background. The external device may have been
       switched off, the data lines may be noisy, system buffers  may  overrun
       or  your  mode  settings  may be wrong.  That's why a reliable software
       should always 1mcatch 22mserial read operations.  In cases of an  error  Tcl
       returns  a general file I/O error.  Then 1mfconfigure -lasterror 22mmay help
       to locate the problem.  The following error codes may be returned.


       1mRXOVER    22mWindows input buffer overrun. The data comes faster than your
                 scripts reads it or your system is overloaded. Use 1mfconfigure0m
                 1m-sysbuffer 22mto avoid a temporary bottleneck and/or  make  your
                 script faster.

       1mTXFULL    22mWindows  output  buffer  overrun.  Complement to RXOVER. This
                 error should practically not happen, because Tcl cares  about
                 the output buffer status.

       1mOVERRUN   22mUART  buffer  overrun  (hardware)  with  data lost.  The data
                 comes faster than the system driver receives it.  Check  your
                 advanced  serial  port  settings  to  enable the FIFO (16550)
                 buffer and/or setup a lower(1) interrupt threshold value.

       1mRXPARITY  22mA parity error has been detected by your UART.  Wrong  parity
                 settings with 1mfconfigure -mode 22mor a noisy data line (RXD) may
                 cause this error.

       1mFRAME     22mA stop-bit error has been detected by your UART.  Wrong  mode
                 settings with 1mfconfigure -mode 22mor a noisy data line (RXD) may
                 cause this error.

       1mBREAK     22mA BREAK condition has been detected by your UART (see above).


1mPORTABILITY ISSUES0m
       1mWindows 22m(all versions)
              Valid  values for 4mfileName24m to open a serial port are of the form
              1mcom4m22mX24m1m:22m, where 4mX24m is a number, generally from 1 to 4.   This  nota-
              tion only works for serial ports from 1 to 9, if the system hap-
              pens 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
              1m\\.\comX22m,  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.

       1mWindows NT0m
              When running Tcl interactively, there may be some strange inter-
              actions between the real console, if one is present, and a  com-
              mand  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 pipe is closed.  This behavior occurs whether the com-
              mand 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.

       1mWindows 950m
              A command pipeline that executes a 16-bit DOS application cannot
              be opened for both reading and writing, since 16-bit DOS  appli-
              cations  that  receive standard input from a pipe and send stan-
              dard 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 inter-
              actions  between the real console, if one is present, and a com-
              mand 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  applica-
              tion,  no  output  is  visible  on the console until 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.

              Whether  or not Tcl is running interactively, if a command pipe-
              line is opened for reading from a 16-bit  DOS  application,  the
              call to 1mopen 22mwill not return until end-of-file has been received
              from the command pipeline's standard output.  If a command pipe-
              line  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.

       1mMacintosh0m
              Opening a serial port is not currently implemented under  Macin-
              tosh.

              Opening  a  command  pipeline  is not supported under Macintosh,
              since applications do not support the concept of standard  input
              or output.

       1mUnix0m
              Valid values for 4mfileName24m to open a serial port are generally of
              the form 1m/dev/tty4m22mX24m, where 4mX24m is 1ma 22mor  1mb22m,  but  the  name  of  any
              pseudo-file  that  maps  to a serial port may be used.  Advanced
              configuration options are only supported for serial  ports  when
              Tcl is built to use the POSIX serial interface.

              When running Tcl interactively, there may be some strange inter-
              actions 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 pipe-
              line 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 1mexec 22mcommand for additional
       information not specific to command pipelines about executing  applica-
       tions on the various platforms

1mEXAMPLE0m
       Open a command pipeline and catch any errors:
              set fl [1mopen 22m"| ls this_file_does_not_exist"]
              set data [read $fl]
              if {[catch {close $fl} err]} {
                  puts "ls command failed: $err"
              }


1mSEE ALSO0m
       file(n),   close(n),   filename(n),  fconfigure(n),  gets(n),  read(n),
       puts(n), exec(n), pid(n), fopen(3)


1mKEYWORDS0m
       access mode, append, create,  file,  non-blocking,  open,  permissions,
