diff options
Diffstat (limited to 'doc/OpenFileChnl.3')
| -rw-r--r-- | doc/OpenFileChnl.3 | 44 |
1 files changed, 40 insertions, 4 deletions
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 45d1410..eeafd08 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -4,13 +4,13 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.9 2000/04/25 00:54:53 ericm Exp $ +'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.10 2001/07/31 19:12:05 vincentdarley Exp $ .so man.macros .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_Ungets \- buffered I/O facilities using channels +Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_Ungets \- buffered I/O facilities using channels .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -46,6 +46,12 @@ int \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) .sp int +\fBTcl_DetachChannel\fR(\fIinterp, channel\fR) +.sp +int +\fBTcl_IsStandardChannel\fR(\fIchannel\fR) +.sp +int \fBTcl_Close\fR(\fIinterp, channel\fR) .sp .VS 8.1 @@ -236,7 +242,11 @@ If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR returns NULL and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR -leaves an error message in \fIinterp\fR's result after any error. +leaves an error message in \fIinterp\fR's result after any error. +As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should +be used in preference to \fBTcl_OpenFileChannel\fR wherever possible. +.PP + .PP The newly created channel is not registered in the supplied interpreter; to register it, use \fBTcl_RegisterChannel\fR, described below. @@ -339,7 +349,33 @@ interpreter, the channel is also closed and destroyed. Code not associated with a Tcl interpreter can call \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl that it no longer holds a reference to that channel. If this is the last -reference to the channel, it will now be closed. +reference to the channel, it will now be closed. \fBTcl_UnregisterChannel\fR +is very similar to \fBTcl_DetachChannel\fR except that it will also +close the channel if no further references to it exist. + +.SH TCL_DETACHCHANNEL +.PP +\fBTcl_DetachChannel\fR removes a channel from the set of channels +accessible in \fIinterp\fR. After this call, Tcl programs will no longer be +able to use the channel's name to refer to the channel in that interpreter. +Beyond that, this command has no further effect. It cannot be used on +the standard channels (stdout, stderr, stdin), and will return +TCL_ERROR if passed one of those channels. +.PP +Code not associated with a Tcl interpreter can call +\fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl +that it no longer holds a reference to that channel. If this is the last +reference to the channel, unlike \fBTcl_UnregisterChannel\fR, +it will not be closed. + +.SH TCL_ISSTANDARDCHANNEL +.PP +\fBTcl_IsStandardChannel\fR tests whether a channel is one of the +three standard channels, stdin, stdout or stderr. If so, it returns +1, otherwise 0. +.PP +No attempt is made to check whether the given channel or the standard +channels are initialized or otherwise valid. .SH TCL_CLOSE .PP |