tcl7.6 User Commands - open






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 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.  Trun-
                    cate  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 control-
                    ling 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 nonblock-
                    ing 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 remain-
     ing  characters  of  fileName are treated as a list of argu-
     ments 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 pipe-
     line is directed to the current standard output unless over-
     ridden  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 execut-  |
          ing 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  pipe-  |
          line  does  not  use  standard  input or output, but is  |
          redirected from or to a file, then the  above  problems  |
          do not occur.                                            |

     Win-  |
          dows 95                                               |
          |                                                        |
          A command pipeline that executes a 16-bit DOS  applica-  |
          tion  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  exe-  |
          cute 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  keys-  |
          trokes  entered at the console will be sent to the com-  |
          mand pipeline and some will be sent to the Tcl  evalua-  |
          tor.   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 pipe-  |
          line 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  com-  |
          mand  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.                                      |

     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  fin-  |
          ished  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 immedi-  |
          ate end-of-file; any data the caller writes to the open  |
          pipe will instead be discarded.                          |

          Since Tcl cannot be run with a real console under  Win-  |
          dows  3.X,  there  are  no interactions between command  |
          pipelines and the console.                               |

     Macin-  |
          tosh                                                  |
          |                                                        |
          Opening a  command  pipeline  is  not  supported  under  |
          Macintosh,  since  applications do not support the con-  |
          cept 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 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  stan-  |
          dard  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,  per-
     missions, pipeline, process