tcl/doc/GetStdChan.3

   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$
   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 in
  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 \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will
  57 construct a new channel to wrap the appropriate platform-specific standard
  58 file handle.  If \fBTcl_SetStdChannel\fR is called before
  59 \fBTcl_GetStdChannel\fR, then the default channel will not be created.
  60 .PP
  61 If one of the standard channels is set to NULL, either by calling
  62 \fBTcl_SetStdChannel\fR with a NULL \fIchannel\fR argument, or by calling
  63 \fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR
  64 will automatically set the standard channel with the newly created channel.  If
  65 more than one standard channel is NULL, then the standard channels will be
  66 assigned starting with standard input, followed by standard output, with
  67 standard error being last.
  68 .PP
  69 See \fBTcl_StandardChannels\fR for a general treatise about standard
  70 channels and the behaviour of the Tcl library with regard to them.
  71 .PP
  72
  73 .SH "SEE ALSO"
  74 Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
  75
  76 .SH KEYWORDS
  77 standard channel, standard input, standard output, standard error