1close(n)                     Tcl Built-In Commands                    close(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       close - Close an open channel
9

SYNOPSIS

11       close channelId ?r(ead)|w(rite)?
12______________________________________________________________________________
13

DESCRIPTION

15       Closes or half-closes the channel given by channelId.
16
17       ChannelId must be an identifier for an open channel such as a Tcl stan‐
18       dard channel (stdin, stdout, or stderr), the return value from an invo‐
19       cation  of  open or socket, or the result of a channel creation command
20       provided by a Tcl extension.
21
22       The single-argument form is a simple “full-close”: all buffered  output
23       is  flushed  to the channel's output device, any buffered input is dis‐
24       carded, the underlying file or device is closed, and channelId  becomes
25       unavailable for use.
26
27       If  the channel is blocking, the command does not return until all out‐
28       put is flushed.  If the channel is nonblocking and there  is  unflushed
29       output,  the  channel remains open and the command returns immediately;
30       output will be flushed in the background and the channel will be closed
31       when all the flushing is complete.
32
33       If  channelId  is  a blocking channel for a command pipeline then close
34       waits for the child processes to complete.
35
36       If the channel is shared between interpreters, then close  makes  chan‐
37       nelId  unavailable  in the invoking interpreter but has no other effect
38       until all of the sharing interpreters have closed  the  channel.   When
39       the  last interpreter in which the channel is registered invokes close,
40       the cleanup actions described above occur. See the interp command for a
41       description of channel sharing.
42
43       Channels  are automatically closed when an interpreter is destroyed and
44       when the process exits.  From 8.6 on  (TIP#398),  nonblocking  channels │
45       are no longer switched to blocking mode when exiting; this guarantees a │
46       timely exit even when the peer or a communication channel  is  stalled. │
47       To  ensure proper flushing of stalled nonblocking channels on exit, one │
48       must now either (a) actively switch them back to blocking  or  (b)  use │
49       the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT,  which when set │
50       and not equal to "0" restores the previous behavior.
51
52       The command returns an empty string, and may generate an  error  if  an
53       error occurs while flushing output.  If a command in a command pipeline
54       created with open returns an error, close generates an  error  (similar
55       to the exec command.)
56
57       The  two-argument form is a “half-close”: given a bidirectional channel │
58       like a socket or command pipeline and a (possibly  abbreviated)  direc‐ │
59       tion, it closes only the sub-stream going in that direction. This means │
60       a shutdown() on a socket, and a close() of one end of a pipe for a com‐ │
61       mand  pipeline.  Then,  the  Tcl-level channel data structure is either │
62       kept or freed depending on whether the other direction is still open.   │
63
64       A single-argument close on an already half-closed bidirectional channel │
65       is defined to just “finish the job”.  A half-close on an already closed │
66       half, or on a wrong-sided unidirectional channel, raises an error.      │
67
68       In the case of a command pipeline, the child-reaping  duty  falls  upon │
69       the shoulders of the last close or half-close, which is thus allowed to │
70       report an abnormal exit error.                                          │
71
72       Currently only sockets and command pipelines support half-close. A  fu‐ │
73       ture extension will allow reflected and stacked channels to do so.
74

EXAMPLE

76       This  illustrates  how  you can use Tcl to ensure that files get closed
77       even when errors happen by combining catch, close and return:
78
79              proc withOpenFile {filename channelVar script} {
80                  upvar 1 $channelVar chan
81                  set chan [open $filename]
82                  catch {
83                      uplevel 1 $script
84                  } result options
85                  close $chan
86                  return -options $options $result
87              }
88

SEE ALSO

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

KEYWORDS

93       blocking, channel, close, nonblocking, half-close
94
95
96
97Tcl                                   7.5                             close(n)
Impressum