distrib/share/tcl/help/tcl/files/close

   1 NAME
   2        close - Close an open channel.
   3
   4 SYNOPSIS
   5        close channelId
   6
   7
   8 DESCRIPTION
   9        Closes the channel given by channelId.
  10
  11        ChannelId must be an identifier for an open channel such as a Tcl stan-
  12        dard channel (stdin, stdout, or stderr), the return value from an invo-
  13        cation  of  open or socket, or the result of a channel creation command
  14        provided by a Tcl extension.
  15
  16        All buffered output is flushed to  the  channel's  output  device,  any
  17        buffered  input  is discarded, the underlying file or device is closed,
  18        and channelId becomes unavailable for use.
  19
  20        If the channel is blocking, the command does not return until all  out-
  21        put  is  flushed.  If the channel is nonblocking and there is unflushed
  22        output, the channel remains open and the command  returns  immediately;
  23        output will be flushed in the background and the channel will be closed
  24        when all the flushing is complete.
  25
  26        If channelId is a blocking channel for a command  pipeline  then  close
  27        waits for the child processes to complete.
  28
  29        If  the  channel is shared between interpreters, then close makes chan-
  30        nelId unavailable in the invoking interpreter but has no  other  effect
  31        until  all  of  the sharing interpreters have closed the channel.  When
  32        the last interpreter in which the channel is registered invokes  close,
  33        the cleanup actions described above occur. See the interp command for a
  34        description of channel sharing.
  35
  36        Channels are automatically closed when an interpreter is destroyed  and
  37        when  the  process  exits.   Channels are switched to blocking mode, to
  38        ensure that all output is correctly flushed before the process exits.
  39
  40        The command returns an empty string, and may generate an  error  if  an
  41        error occurs while flushing output.  If a command in a command pipeline
  42        created with open returns an error, close generates an  error  (similar
  43        to the exec command.)
  44
  45 EXAMPLE
  46        This  illustrates  how  you can use Tcl to ensure that files get closed
  47        even when errors happen by combining catch, close and return:
  48               proc withOpenFile {filename channelVar script} {
  49                   upvar 1 $channelVar chan
  50                   set chan [open $filename]
  51                   catch {
  52                       uplevel 1 $script
  53                   } result options
  54                   close $chan
  55                   return -options $options $result
  56               }
  57
  58
  59 SEE ALSO
  60        file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
  61
  62
  63 KEYWORDS