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


       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.

       Note that if you are going to be reading or writing binary |
       data from the channel created by this command, you  should |
       use  the  fconfigure  command  to  change the -translation |
       option of the channel to binary  before  transferring  any |
       binary  data.   This is in contrast to the ``b'' character |
       passed as part of the equivalent of the  access  parameter |
       to some versions of the C library fopen() function.


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

       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.


SERIAL COMMUNICATIONS

       If  fileName  refers  to a serial port, then the specified |
       serial port is opened and initialized in a platform-depen­ |
       dent 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 connec­ |
              tion speed.  Parity is one of  the  following  let­ |
              ters:  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 com­ |
              munication 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).

       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 |

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

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

       additional  information  not specific to command pipelines |
       about executing applications on the various platforms      |


SEE ALSO |

       file(n), close(n),  filename(n),  fconfigure(n),  gets(n), |
       read(n), puts(n), exec(n), fopen(1)                        |


KEYWORDS |

       access  mode,  append,  create,  file, non-blocking, open, |
       permissions, pipeline, process, serial                     |


Man(1) output converted with man2html