Attachment "doc.diff" to
ticket [402725ffff]
added by
andreas_kupries
2001-08-25 04:05:29.
? doc/foo
Index: doc/CrtChannel.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/CrtChannel.3,v
retrieving revision 1.9
diff -u -r1.9 CrtChannel.3
--- doc/CrtChannel.3 2001/03/30 23:06:39 1.9
+++ doc/CrtChannel.3 2001/08/24 21:02:36
@@ -199,6 +199,12 @@
mode indicated by \fImask\fR.
For a discussion of channel drivers, their operations and the
\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
+\fBTcl_CreateChannel\fR interacts with the code managing the standard
+channels. Once a standard channel was initialized to its default
+through a call to \fBTcl_GetStdChannel\fR before a call to
+\fBTcl_SetStdChannel\fR closing this standard channel will cause the
+next call to \fBTcl_CreateChannel\fR to make the new channel the new
+standard channel too.
.PP
\fBTcl_GetChannelInstanceData\fR returns the instance data associated with
the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
@@ -813,7 +819,7 @@
implementation (in 8.2.0 to 8.3.1).
.SH "SEE ALSO"
-Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3)
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
.SH KEYWORDS
blocking, channel driver, channel registration, channel type, nonblocking
Index: doc/GetStdChan.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/GetStdChan.3,v
retrieving revision 1.2
diff -u -r1.2 GetStdChan.3
--- doc/GetStdChan.3 1998/09/14 18:39:48 1.2
+++ doc/GetStdChan.3 2001/08/24 21:02:36
@@ -59,15 +59,28 @@
\fBTcl_GetStdChannel\fR, then the default channel will not be created.
.PP
If one of the standard channels is set to NULL, either by calling
-\fBTcl_SetStdChannel\fR with a null \fIchannel\fR argument, or by calling
+\fBTcl_SetStdChannel\fR with a NULL \fIchannel\fR argument, or by calling
\fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR
will automatically set the standard channel with the newly created channel. If
more than one standard channel is NULL, then the standard channels will be
assigned starting with standard input, followed by standard output, with
standard error being last.
+.PP
+The above is true only if the standard channels were initialized by
+\fBTcl_GetStdChannel\fR. \fBTcl_CreateChannel\fR will not fill an
+empty slot if that slot was never initialized with its default value,
+i.e. through a call to \fBTcl_GetStdChannel\fR before
+\fBTcl_SetStdChannel\fR. This means than an application which did not
+initialize its standard channels to their defaults is not able to
+replace them via \fBTcl_CreateChannel\fR after the ones set via
+\fBTcl_SetStdChannel\fR were closed.
+.PP
+Applications using \fBTcl_Main\fR as their main code, like \fBtclsh\fR
+itself, do not have to worry about this as \fBTcl_Main\fR does
+initialize the standard channels to their default values.
.SH "SEE ALSO"
-Tcl_Close(3), Tcl_CreateChannel(3)
+Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
.SH KEYWORDS
standard channel, standard input, standard output, standard error
Index: doc/Tcl_Main.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Tcl_Main.3,v
retrieving revision 1.3
diff -u -r1.3 Tcl_Main.3
--- doc/Tcl_Main.3 2000/11/03 20:20:55 1.3
+++ doc/Tcl_Main.3 2001/08/24 21:02:36
@@ -77,5 +77,13 @@
.CE
.VE 8.4
+.PP
+\fBTcl_Main\fR uses \fBTcl_GetStdChannel\fR to initialize the standard
+channels to their default values. The effects of this are explained in
+the manpage of \fBTcl_GetStdChannel\fR.
+
+.SH "SEE ALSO"
+Tcl_GetStdChannel(3)
+
.SH KEYWORDS
application-specific initialization, command-line arguments, main program
Index: doc/tclsh.1
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/tclsh.1,v
retrieving revision 1.4
diff -u -r1.4 tclsh.1
--- doc/tclsh.1 2001/08/06 20:43:05 1.4
+++ doc/tclsh.1 2001/08/24 21:02:36
@@ -123,5 +123,23 @@
if \fBtcl_prompt2\fR isn't set then no prompt is output for
incomplete commands.
+.SH "STANDARD CHANNELS"
+.PP
+.VS
+Tclsh creates three channels by default (on platforms where the
+underlying operating system supports this behaviour) named \fBstdin\fR
+(which is read-only) \fBstdout\fR and \fBstderr\fR (both of which are
+write only.) The intended semantics of their use is very similar to
+that of the equivalently-named file handles in C - input, either as
+typing by the user or data from a file or pipe, comes from
+\fBstdin\fR, output, either to the user's terminal or to a file or
+pipe, goes to \fBstdout\fR, and errors are reported (typically to the
+user's terminal) to \fBstderr\fR - and the channels are
+\fBfconfigure\fRd to support this usage.
+.VE
+
+.SH "SEE ALSO"
+fconfigure(1), tclvars(1)
+
.SH KEYWORDS
argument, interpreter, prompt, script file, shell
