Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
open(n)			     Tcl Built-In Commands		       open(n)

______________________________________________________________________________

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

       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 ex-
		      ists.  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 ac-
		      cess 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, mak- |
       ing 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 bi- |
		      nary 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-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 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	 inte-
       ger)  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 stan-
       dard 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	 pipe-
       line  returns an	error (according to the	definition in exec), a Tcl er-
       ror is generated	when close is called on	the channel unless  the	 pipe-
       line  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 val-
       ues 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 configu-
       ration 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 hand-
	      shake control. Note that not all handshake types maybe supported
	      by  your	operating  system. The type parameter is case-indepen-
	      dent.

	      If type is none then any handshake is switched off.  rtscts  ac-
	      tivates  hardware	 handshake. Hardware handshake signals are de-
	      scribed 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  be-
	      tween the	reception of two bytes in milliseconds.	 For Unix sys-
	      tems the granularity is 100 milliseconds.	 The  -timeout	option
	      does not affect write operations or nonblocking reads.  This op-
	      tion 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 op-
	      tion 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 de-
	      fault 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 be-
	      tween 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 de-
	      fault).

       -sysbuffer inSize

       -sysbuffer {inSize outSize}
	      (Windows only). This option is used to change the	size  of  Win-
	      dows  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 in-
	      put buffer size, in the second form both input and  output  buf-
	      fers 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 er-
	      ror 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 se-
       rial 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	outgo-
       ing  data,  status  lines  and handshaking. Here	we are using the terms
       workstation for your computer and modem for the	external  device,  be-
       cause  some signal names	(DCD, RI) come from modems. Of course your ex-
       ternal 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	 work-
	      station is ready to establish a link. DTR	is often enabled auto-
	      matically	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 de-
	      tects 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 communi-
	      cations 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 er-
		 ror  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) buf-
		 fer 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
	      Valid  values for	fileName to open a serial port are of the form
	      comX, where X is a number, generally from	1 to 9.	 A legacy form
	      accepted	as  well is comX:. This	notation only works for	serial
	      ports from 1 to 9.  An attempt to	open a serial port  that  does
	      not  exist  or has a number greater than 9 will fail.  An	alter-
	      nate form	of  opening  serial  ports  is	to  use	 the  filename
	      //./comX,	 where	X  is  any number that corresponds to a	serial
	      port.

	      When running Tcl interactively, there may	be some	strange	inter-
	      actions  between the real	console, if one	is present, and	a com-
	      mand 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 un-
	      til  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 com-
	      mand  pipeline  does  not	 use  standard input or	output,	but is
	      redirected from or to a file, then the above problems do not oc-
	      cur.

       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	inter-
	      actions 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 pipe-
	      line 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  applica-
       tions 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(n),	  close(n),   filename(n),  fconfigure(n),  gets(n),  read(n),
       puts(n),	exec(n), pid(n), fopen(3)

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

Tcl				      8.3			       open(n)

NAME | SYNOPSIS | DESCRIPTION | COMMAND PIPELINES | SERIAL COMMUNICATIONS | SERIAL PORT SIGNALS | ERROR CODES (Windows only) | PORTABILITY ISSUES | EXAMPLE | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=open.tcl85&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help