1 | '\" |
---|
2 | '\" Copyright (c) 1996 by Sun Microsystems, Inc. |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: GetStdChan.3,v 1.8 2007/12/13 15:22:31 dgp Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures" |
---|
11 | .BS |
---|
12 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
13 | .SH NAME |
---|
14 | Tcl_GetStdChannel, Tcl_SetStdChannel \- procedures for retrieving and replacing the standard channels |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | Tcl_Channel |
---|
20 | \fBTcl_GetStdChannel\fR(\fItype\fR) |
---|
21 | .sp |
---|
22 | \fBTcl_SetStdChannel\fR(\fIchannel, type\fR) |
---|
23 | .sp |
---|
24 | .SH ARGUMENTS |
---|
25 | .AS Tcl_Channel channel |
---|
26 | .AP int type in |
---|
27 | The identifier for the standard channel to retrieve or modify. Must be one of |
---|
28 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR. |
---|
29 | .AP Tcl_Channel channel in |
---|
30 | The channel to use as the new value for the specified standard channel. |
---|
31 | .BE |
---|
32 | |
---|
33 | .SH DESCRIPTION |
---|
34 | .PP |
---|
35 | Tcl defines three special channels that are used by various I/O related |
---|
36 | commands if no other channels are specified. The standard input channel |
---|
37 | has a channel name of \fBstdin\fR and is used by \fBread\fR and \fBgets\fR. |
---|
38 | The standard output channel is named \fBstdout\fR and is used by |
---|
39 | \fBputs\fR. The standard error channel is named \fBstderr\fR and is used for |
---|
40 | reporting errors. In addition, the standard channels are inherited by any |
---|
41 | child processes created using \fBexec\fR or \fBopen\fR in the absence of any |
---|
42 | other redirections. |
---|
43 | .PP |
---|
44 | The standard channels are actually aliases for other normal channels. The |
---|
45 | current channel associated with a standard channel can be retrieved by calling |
---|
46 | \fBTcl_GetStdChannel\fR with one of |
---|
47 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR as the \fItype\fR. The |
---|
48 | return value will be a valid channel, or NULL. |
---|
49 | .PP |
---|
50 | A new channel can be set for the standard channel specified by \fItype\fR |
---|
51 | by calling \fBTcl_SetStdChannel\fR with a new channel or NULL in the |
---|
52 | \fIchannel\fR argument. If the specified channel is closed by a later call to |
---|
53 | \fBTcl_Close\fR, then the corresponding standard channel will automatically be |
---|
54 | set to NULL. |
---|
55 | .PP |
---|
56 | If a non-NULL value for \fIchannel\fR is passed to \fBTcl_SetStdChannel\fR, |
---|
57 | then that same value should be passed to \fBTcl_RegisterChannel\fR, like so: |
---|
58 | .CS |
---|
59 | Tcl_RegisterChannel(NULL, channel); |
---|
60 | .CE |
---|
61 | This is a workaround for a misfeature in \fBTcl_SetStdChannel\fR that it |
---|
62 | fails to do some reference counting housekeeping. This misfeature cannot |
---|
63 | be corrected without contradicting the assumptions of some existing |
---|
64 | code that calls \fBTcl_SetStdChannel\fR. |
---|
65 | .PP |
---|
66 | If \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will |
---|
67 | construct a new channel to wrap the appropriate platform-specific standard |
---|
68 | file handle. If \fBTcl_SetStdChannel\fR is called before |
---|
69 | \fBTcl_GetStdChannel\fR, then the default channel will not be created. |
---|
70 | .PP |
---|
71 | If one of the standard channels is set to NULL, either by calling |
---|
72 | \fBTcl_SetStdChannel\fR with a NULL \fIchannel\fR argument, or by calling |
---|
73 | \fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR |
---|
74 | will automatically set the standard channel with the newly created channel. If |
---|
75 | more than one standard channel is NULL, then the standard channels will be |
---|
76 | assigned starting with standard input, followed by standard output, with |
---|
77 | standard error being last. |
---|
78 | .PP |
---|
79 | See \fBTcl_StandardChannels\fR for a general treatise about standard |
---|
80 | channels and the behaviour of the Tcl library with regard to them. |
---|
81 | |
---|
82 | .SH "SEE ALSO" |
---|
83 | Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1) |
---|
84 | |
---|
85 | .SH KEYWORDS |
---|
86 | standard channel, standard input, standard output, standard error |
---|