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

FreeBSD Manual Pages


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


       close - Close an	open channel

       close channelId ?r(ead)|w(rite)?

       Closes or half-closes the channel given by channelId.

       ChannelId must be an identifier for an open channel such	as a Tcl stan-
       dard channel (stdin, stdout, or stderr),	the return value from an invo-
       cation  of  open	or socket, or the result of a channel creation command
       provided	by a Tcl extension.

       The single-argument form	is a simple "full-close": all buffered	output
       is  flushed  to the channel's output device, any	buffered input is dis-
       carded, the underlying file or device is	closed,	and channelId  becomes
       unavailable for use.

       If  the channel is blocking, the	command	does not return	until all out-
       put is flushed.	If the channel is nonblocking and there	 is  unflushed
       output,	the  channel remains open and the command returns immediately;
       output will be flushed in the background	and the	channel	will be	closed
       when all	the flushing is	complete.

       If  channelId  is  a blocking channel for a command pipeline then close
       waits for the child processes to	complete.

       If the channel is shared	between	interpreters, then close  makes	 chan-
       nelId  unavailable  in the invoking interpreter but has no other	effect
       until all of the	sharing	interpreters have closed  the  channel.	  When
       the  last interpreter in	which the channel is registered	invokes	close,
       the cleanup actions described above occur. See the interp command for a
       description of channel sharing.

       Channels	 are automatically closed when an interpreter is destroyed and
       when the	process	exits.	From 8.6 on  (TIP#398),	 nonblocking  channels |
       are no longer switched to blocking mode when exiting; this guarantees a |
       timely exit even	when the peer or a communication channel  is  stalled. |
       To  ensure proper flushing of stalled nonblocking channels on exit, one |
       must now	either (a) actively switch them	back to	blocking  or  (b)  use |
       the environment variable	TCL_FLUSH_NONBLOCKING_ON_EXIT,	which when set |
       and not equal to	"0" restores the previous behavior.

       The command returns an empty string, and	may generate an	 error	if  an
       error occurs while flushing output.  If a command in a command pipeline
       created with open returns an error, close generates an  error  (similar
       to the exec command.)

       The  two-argument form is a "half-close": given a bidirectional channel |
       like a socket or	command	pipeline and a (possibly  abbreviated)	direc- |
       tion, it	closes only the	sub-stream going in that direction. This means |
       a shutdown() on a socket, and a close() of one end of a pipe for	a com- |
       mand  pipeline.	Then,  the  Tcl-level channel data structure is	either |
       kept or freed depending on whether the other direction is still open.   |

       A single-argument close on an already half-closed bidirectional channel |
       is defined to just "finish the job".  A half-close on an	already	closed |
       half, or	on a wrong-sided unidirectional	channel, raises	an error.      |

       In the case of a	command	pipeline, the child-reaping  duty  falls  upon |
       the shoulders of	the last close or half-close, which is thus allowed to |
       report an abnormal exit error.					       |

       Currently only sockets and command pipelines support half-close.	A  fu- |
       ture extension will allow reflected and stacked channels	to do so.

       This  illustrates  how  you can use Tcl to ensure that files get	closed
       even when errors	happen by combining catch, close and return:

	      proc withOpenFile	{filename channelVar script} {
		  upvar	1 $channelVar chan
		  set chan [open $filename]
		  catch	{
		      uplevel 1	$script
		  } result options
		  close	$chan
		  return -options $options $result

       file(n),	open(n), socket(n), eof(n), Tcl_StandardChannels(3)

       blocking, channel, close, nonblocking, half-close

Tcl				      7.5			      close(n)


Want to link to this manual page? Use this URL:

home | help