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 or command pipeline and returns
       a channel identifier that may be used  in  future  invoca-
       tions  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, cre-
                      ate 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.  The file
                      must already exist, and the file  is  posi-
                      tioned  so that new data is appended to 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  con-
                      trolling terminal of the process.

       NONBLOCK       Prevents  the  process  from blocking while
                      opening the file, and  possibly  in  subse-
                      quent  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 fconfigure command to put a file
                      in nonblocking mode).  For details refer to
                      your system documentation on the open  sys-
                      tem 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,  permis-
       sions  (an integer) is used to set the permissions for the
       new file in conjunction with the process's file mode  cre-
       ation 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 out-
       put 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.


PORTABILITY ISSUES
       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 out-
              put 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 redi-
              rected 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  actu-
              ally  closed.   This  problem occurs because 16-bit
              DOS  applications   are   run   synchronously,   as
              described above.

       Windows 3.X
              A command pipeline can execute 16-bit or 32-bit DOS
              or Windows applications, but the call to open  will
              not  return  until the last program in the pipeline
              has finished executing; command pipelines run  syn-
              chronously.   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 dis-
              carded.

              Since Tcl cannot be run with a real  console  under
              Windows 3.X, there are no interactions between com-
              mand pipelines and the console.

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

       Unix
              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 read-
              ing, 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,
       permissions, pipeline, process
