Provided by: tcl8.5-doc_8.5.15-2ubuntu1_all bug

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 does not
                      exist, create a new file.

       w+             Open the file for reading and writing.  Truncate it if it  exists.   If  it
                      does not exist, create a new file.

       a              Open  the  file for writing only.  If the file does not exist, create a new
                      empty file.  Set the file pointer to the end of  the  file  prior  to  each
                      write.

       a+             Open  the file for reading and writing.  If the file does not exist, create
                      a new empty file.  Set the initial access position  to the end of the file. │

       All of the legal access values above may have the character b added as the second or third │
       character  in  the value to indicate that the opened channel should be configured with the │
       -translation binary option, making the channel suitable for reading or writing  of  binary │
       data.

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

       BINARY                                                                                     │
                      Configure the opened channel with the -translation binary option.

       CREAT          Create the file if it does not 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.   The
       id  of  the  spawned  process  is accessible through the pid command, using the channel id
       returned by open as argument.

       If the command (or one of the commands) executed in the command pipeline returns an  error
       (according  to  the  definition in exec), a Tcl error is generated when close is called on
       the channel unless the pipeline is in non-blocking mode then no exit status is returned (a
       silent close with -blocking 0).

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

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.

       The fconfigure command can be used to  query  and  set  additional  configuration  options
       specific to serial ports (where supported):

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

       -handshake type
              (Windows  and Unix). This option is used to setup automatic handshake control. Note
              that not all handshake types maybe supported by your  operating  system.  The  type
              parameter is case-independent.

              If  type  is  none  then  any handshake is switched off.  rtscts activates hardware
              handshake. Hardware handshake signals are described below.  For software  handshake
              xonxoff  the  handshake  characters  can  be  redefined with -xchar.  An additional
              hardware handshake dtrdsr is available only under Windows.   There  is  no  default
              handshake  configuration,  the  initial  value  depends  on  your  operating system
              settings.  The -handshake option cannot be queried.

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

       -timeout msec
              (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  -timeout
              option  does  not affect write operations or nonblocking reads.  This option cannot
              be queried.

       -ttycontrol {signal boolean signal boolean ...}
              (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 signal names are
              case-independent.  {RTS 1 DTR 0} sets the RTS output to high and the DTR output  to
              low.   The  BREAK  condition (see below) is enabled and disabled with {BREAK 1} and
              {BREAK 0} respectively.  It is not a good idea to change the RTS  (or  DTR)  signal
              with  active  hardware  handshake rtscts (or dtrdsr).  The result is unpredictable.
              The -ttycontrol option cannot be queried.

       -ttystatus
              (Windows and Unix). The -ttystatus option 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. {CTS 1 DSR 0 RING  1  DCD  0}.   The
              signal names are returned upper case.

       -xchar {xonChar xoffChar}
              (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.

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

       -sysbuffer inSize

       -sysbuffer {inSize outSize}
              (Windows only). This option is used to change the size of  Windows  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.

       -lasterror
              (Windows only). This option is query only.   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.  See below for an explanation of  the
              various error codes.

SERIAL PORT SIGNALS

       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 outgoing data, status lines and handshaking. Here we are using the  terms  workstation
       for  your  computer and modem 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.

       TXD(output)
              Transmitted Data: Outgoing serial data.

       RXD(input)
              Received Data:Incoming serial data.

       RTS(output)
              Request  To  Send:  This  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.

       CTS(input)
              Clear  To Send: The complement to RTS. Indicates that the modem is ready to receive
              data.

       DTR(output)
              Data Terminal Ready: This signal tells the modem that the workstation is  ready  to
              establish  a  link.  DTR  is  often enabled automatically whenever a serial port is
              opened.

       DSR(input)
              Data Set Ready: The complement to DTR. Tells the  workstation  that  the  modem  is
              ready to establish a link.

       DCD(input)
              Data  Carrier  Detect:  This  line  becomes active when a modem detects a “Carrier”
              signal.

       RI(input)
              Ring Indicator: Goes active when the modem detects an incoming call.

       BREAK  A 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 communications
              line or change the operating mode of communications hardware.

ERROR CODES (Windows only)

       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  is  why  a
       reliable  software  should  always catch serial read operations.  In cases of an error Tcl
       returns a general file I/O error.  Then fconfigure  -lasterror  may  help  to  locate  the
       problem.  The following error codes may be returned.

       RXOVER    Windows  input  buffer overrun. The data comes faster than your scripts reads it
                 or your system is overloaded. Use fconfigure -sysbuffer  to  avoid  a  temporary
                 bottleneck and/or make your script faster.

       TXFULL    Windows   output  buffer  overrun.  Complement  to  RXOVER.  This  error  should
                 practically not happen, because Tcl cares about the output buffer status.

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

       RXPARITY  A parity error has been detected by  your  UART.   Wrong  parity  settings  with
                 fconfigure -mode or a noisy data line (RXD) may cause this error.

       FRAME     A  stop-bit  error  has  been  detected  by your UART.  Wrong mode settings with
                 fconfigure -mode or a noisy data line (RXD) may cause this error.

       BREAK     A BREAK condition has been detected by your UART (see above).

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

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

EXAMPLE

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

SEE ALSO

       file(3tcl),   close(3tcl),   filename(3tcl),   fconfigure(3tcl),  gets(3tcl),  read(3tcl),
       puts(3tcl), exec(3tcl), pid(3tcl), fopen(3)

KEYWORDS

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