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,  serial  port,  or  command
       pipeline and returns a channel identifier that may be used
       in  future  invocations  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,
                      create 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.  If the
                      file doesn't  exist,  create  a  new  empty
                      file.   Set the initial access position  to
                      the end of 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
       meanings.   One of the flags must be either RDONLY, WRONLY
       or RDWR.

       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
                      controlling terminal of the process.

       NONBLOCK       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 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,
       permissions (an integer) is used to  set  the  permissions
       for  the  new  file in conjunction with the process's file
       mode creation 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
       output  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
       overridden by the command.

SERIAL COMMUNICATIONS
       If fileName refers to a serial port,  then  the  specified
       serial  port  is  opened  and  initialized  in a platform-
       dependent manner.  Acceptable values for the  fileName  to
       use to open a serial port are described in the PORTABILITY
       ISSUES section.


CONFIGURATION OPTIONS
       The fconfigure command can be used to query  and  set  the
       following configuration option for open serial ports:

       -mode baud,parity,data,stop
              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 baud
              rate  is  a  simple  integer  that  specifies   the
              connection  speed.   Parity is one of the following
              letters: n, o, e, m, s; respectively signifying the
              parity  options  of  ``none'',  ``odd'',  ``even'',
              ``mark'', or ``space''.  Data is the number of data
              bits  and  should  be an integer from 5 to 8, while
              stop is the number of stop bits and should  be  the
              integer 1 or 2.

       -pollinterval msec
              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).

       -lasterror
              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, read or puts returns a general
              Tcl  file  I/O error.  fconfigure -lasterror can be
              called to get a list of error details  (e.g.  FRAME
              RXOVER).


PORTABILITY ISSUES
       Windows (all versions)
              Valid values for fileName to open a serial port are
              of the form comX:, where X 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 \\.\comX, 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.

       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
              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.

              Whether  or  not Tcl is running interactively, if a
              command pipeline  is  opened  for  reading  from  a
              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
              actually   closed.   This  problem  occurs  because
              16-bit DOS applications are run  synchronously,  as
              described above.

       Macintosh
              Opening  a serial port is not currently implemented
              under Macintosh.

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

       Unix
              Valid values for fileName to open a serial port are
              generally of the form /dev/ttyX, where X is a or b,
              but the name of any  pseudo-file  that  maps  to  a
              serial port may be used.

              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.

       See the PORTABILITY ISSUES section of the exec command for
       additional  information  not specific to command pipelines
       about executing applications on the various platforms

SEE ALSO
       close(n), filename(n), gets(n), read(n), puts(n), exec(n)

KEYWORDS
       access mode, append,  create,  file,  non-blocking,  open,
