| [25] | 1 | '\" |
|---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
|---|
| 3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
|---|
| 4 | '\" |
|---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
|---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
|---|
| 7 | '\" |
|---|
| 8 | '\" RCS: @(#) $Id: close.n,v 1.13 2007/12/13 15:22:32 dgp Exp $ |
|---|
| 9 | '\" |
|---|
| 10 | .so man.macros |
|---|
| 11 | .TH close n 7.5 Tcl "Tcl Built-In Commands" |
|---|
| 12 | .BS |
|---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
|---|
| 14 | .SH NAME |
|---|
| 15 | close \- Close an open channel |
|---|
| 16 | .SH SYNOPSIS |
|---|
| 17 | \fBclose \fIchannelId\fR |
|---|
| 18 | .BE |
|---|
| 19 | |
|---|
| 20 | .SH DESCRIPTION |
|---|
| 21 | .PP |
|---|
| 22 | Closes the channel given by \fIchannelId\fR. |
|---|
| 23 | .PP |
|---|
| 24 | \fIChannelId\fR must be an identifier for an open channel such as a |
|---|
| 25 | Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), |
|---|
| 26 | the return value from an invocation of \fBopen\fR or \fBsocket\fR, or |
|---|
| 27 | the result of a channel creation command provided by a Tcl extension. |
|---|
| 28 | .PP |
|---|
| 29 | All buffered output is flushed to the channel's output device, |
|---|
| 30 | any buffered input is discarded, the underlying file or device is closed, |
|---|
| 31 | and \fIchannelId\fR becomes unavailable for use. |
|---|
| 32 | .PP |
|---|
| 33 | If the channel is blocking, the command does not return until all output |
|---|
| 34 | is flushed. |
|---|
| 35 | If the channel is nonblocking and there is unflushed output, the |
|---|
| 36 | channel remains open and the command |
|---|
| 37 | returns immediately; output will be flushed in the background and the |
|---|
| 38 | channel will be closed when all the flushing is complete. |
|---|
| 39 | .PP |
|---|
| 40 | If \fIchannelId\fR is a blocking channel for a command pipeline then |
|---|
| 41 | \fBclose\fR waits for the child processes to complete. |
|---|
| 42 | .PP |
|---|
| 43 | If the channel is shared between interpreters, then \fBclose\fR |
|---|
| 44 | makes \fIchannelId\fR unavailable in the invoking interpreter but has no |
|---|
| 45 | other effect until all of the sharing interpreters have closed the |
|---|
| 46 | channel. |
|---|
| 47 | When the last interpreter in which the channel is registered invokes |
|---|
| 48 | \fBclose\fR, the cleanup actions described above occur. See the |
|---|
| 49 | \fBinterp\fR command for a description of channel sharing. |
|---|
| 50 | .PP |
|---|
| 51 | Channels are automatically closed when an interpreter is destroyed and |
|---|
| 52 | when the process exits. Channels are switched to blocking mode, to ensure |
|---|
| 53 | that all output is correctly flushed before the process exits. |
|---|
| 54 | .PP |
|---|
| 55 | The command returns an empty string, and may generate an error if |
|---|
| 56 | an error occurs while flushing output. If a command in a command |
|---|
| 57 | pipeline created with \fBopen\fR returns an error, \fBclose\fR |
|---|
| 58 | generates an error (similar to the \fBexec\fR command.) |
|---|
| 59 | .SH EXAMPLE |
|---|
| 60 | This illustrates how you can use Tcl to ensure that files get closed |
|---|
| 61 | even when errors happen by combining \fBcatch\fR, \fBclose\fR and |
|---|
| 62 | \fBreturn\fR: |
|---|
| 63 | .CS |
|---|
| 64 | proc withOpenFile {filename channelVar script} { |
|---|
| 65 | upvar 1 $channelVar chan |
|---|
| 66 | set chan [open $filename] |
|---|
| 67 | catch { |
|---|
| 68 | uplevel 1 $script |
|---|
| 69 | } result options |
|---|
| 70 | \fBclose\fR $chan |
|---|
| 71 | return -options $options $result |
|---|
| 72 | } |
|---|
| 73 | .CE |
|---|
| 74 | |
|---|
| 75 | .SH "SEE ALSO" |
|---|
| 76 | file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) |
|---|
| 77 | |
|---|
| 78 | .SH KEYWORDS |
|---|
| 79 | blocking, channel, close, nonblocking |
|---|
