summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorandreas_kupries <akupries@shaw.ca>2001-09-14 19:20:39 (GMT)
committerandreas_kupries <akupries@shaw.ca>2001-09-14 19:20:39 (GMT)
commite670c6f17e7ac704c3c6f117912e45313254d4d9 (patch)
tree601c942962a61099835ec8cca4eb537578460b9d /doc
parent1aa543f158267b3810d76b69186f8aa94aec2c84 (diff)
downloadtcl-e670c6f17e7ac704c3c6f117912e45313254d4d9.zip
tcl-e670c6f17e7ac704c3c6f117912e45313254d4d9.tar.gz
tcl-e670c6f17e7ac704c3c6f117912e45313254d4d9.tar.bz2
* doc/gets.n:
* doc/read.n: * doc/puts.n: * doc/flush.n: * doc/fconfigure.n: * doc/flush.n: * doc/eof.n: * doc/seek.n: * doc/tell.n: * doc/close.n: * doc/fileevent.n: Added references to the Tcl standard channels. Item [219250], reported by David LeBlanc <whisper@oz.net>. Thanks to Christopher Nelson <chris@pinebush.com> for doing editorial work.
Diffstat (limited to 'doc')
-rw-r--r--doc/close.n16
-rw-r--r--doc/eof.n11
-rw-r--r--doc/fblocked.n10
-rw-r--r--doc/fconfigure.n27
-rw-r--r--doc/fileevent.n15
-rw-r--r--doc/flush.n15
-rw-r--r--doc/gets.n13
-rw-r--r--doc/puts.n17
-rw-r--r--doc/read.n18
-rw-r--r--doc/seek.n14
-rw-r--r--doc/tell.n11
11 files changed, 126 insertions, 41 deletions
diff --git a/doc/close.n b/doc/close.n
index 86b07ca..501d282 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: close.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $
+'\" RCS: @(#) $Id: close.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH close n 7.5 Tcl "Tcl Built-In Commands"
@@ -19,9 +19,15 @@ close \- Close an open channel.
.SH DESCRIPTION
.PP
-Closes the channel given by \fIchannelId\fR. \fIChannelId\fR must be a
-channel identifier such as the return value from a previous \fBopen\fR
-or \fBsocket\fR command.
+Closes the channel given by \fIchannelId\fR.
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
+the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
+the result of a channel creation command provided by a Tcl extension.
+.VE
+.PP
All buffered output is flushed to the channel's output device,
any buffered input is discarded, the underlying file or device is closed,
and \fIchannelId\fR becomes unavailable for use.
@@ -56,7 +62,7 @@ The command returns an empty string, and may generate an error if
an error occurs while flushing output.
.SH "SEE ALSO"
-file(n), open(n), socket(n), eof(n)
+file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
.SH KEYWORDS
blocking, channel, close, nonblocking
diff --git a/doc/eof.n b/doc/eof.n
index f79d91a..ad5f90f 100644
--- a/doc/eof.n
+++ b/doc/eof.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: eof.n,v 1.3 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: eof.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH eof n 7.5 Tcl "Tcl Built-In Commands"
@@ -22,9 +22,16 @@ eof \- Check for end of file condition on channel
Returns 1 if an end of file condition occurred during the most
recent input operation on \fIchannelId\fR (such as \fBgets\fR),
0 otherwise.
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
+the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
+the result of a channel creation command provided by a Tcl extension.
+.VE
.SH "SEE ALSO"
-file(n), open(n), close(n), fblocked(n)
+file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
.SH KEYWORDS
channel, end of file
diff --git a/doc/fblocked.n b/doc/fblocked.n
index 96001f6..7f8fe54 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: fblocked.n,v 1.3 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: fblocked.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
.so man.macros
.TH fblocked n 7.5 Tcl "Tcl Built-In Commands"
.BS
@@ -25,9 +25,15 @@ characters available for input and no end-of-line sequence, \fBgets\fR
returns an empty string and a subsequent call to \fBfblocked\fR will
return 1.
.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
+the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
+the result of a channel creation command provided by a Tcl extension.
+.VE
.SH "SEE ALSO"
-gets(n), open(n), read(n)
+gets(n), open(n), read(n), Tcl_StandardChannels(3)
.SH KEYWORDS
blocking, nonblocking
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 77b8ec2..7689d20 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: fconfigure.n,v 1.4 1999/07/07 18:59:52 stanton Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH fconfigure n 8.1 Tcl "Tcl Built-In Commands"
@@ -19,11 +19,18 @@ fconfigure \- Set and get options on a channel
\fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR?
.fi
.BE
-
.SH DESCRIPTION
.PP
The \fBfconfigure\fR command sets and retrieves options for channels.
-\fIChannelId\fR identifies the channel for which to set or query an option.
+.PP
+.VS
+\fIChannelId\fR identifies the channel for which to set or query an
+option and must refer to an open channel such as a Tcl standard
+channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), the return
+value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
+of a channel creation command provided by a Tcl extension.
+.VE
+.PP
If no \fIname\fR or \fIvalue\fR arguments are supplied, the command
returns a list containing alternating option names and values for the channel.
If \fIname\fR is supplied but no \fIvalue\fR then the command returns
@@ -192,8 +199,20 @@ platforms.
.RE
.PP
+.VS
+.SH "STANDARD CHANNELS"
+.PP
+The Tcl standard channels (\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR)
+can be configured through this command like every other channel opened
+by the Tcl library. Beyond the standard options described above they
+will also support any special option according to their current type.
+If, for example, a Tcl application is started by the \fBinet\fR
+super-server common on Unix system its Tcl standard channels will be
+sockets and thus support the socket options.
+.VE
+
.SH "SEE ALSO"
-close(n), flush(n), gets(n), puts(n), read(n), socket(n)
+close(n), flush(n), gets(n), puts(n), read(n), socket(n), Tcl_StandardChannels(3)
.SH KEYWORDS
blocking, buffering, carriage return, end of line, flushing, linemode,
diff --git a/doc/fileevent.n b/doc/fileevent.n
index f5b6b1f..037d361 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: fileevent.n,v 1.3 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: fileevent.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
@@ -34,9 +34,14 @@ appear to the user to ``freeze up''. With \fBfileevent\fR, the process can
tell when data is present and only invoke \fBgets\fR or \fBread\fR when
they won't block.
.PP
-The \fIchannelId\fR argument to \fBfileevent\fR refers to an open channel,
-such as the return value from a previous \fBopen\fR or \fBsocket\fR
-command.
+.VS
+The \fIchannelId\fR argument to \fBfileevent\fR refers to an open
+channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR,
+or \fBstderr\fR), the return value from an invocation of \fBopen\fR
+or \fBsocket\fR, or the result of a channel creation command provided
+by a Tcl extension.
+.VE
+.PP
If the \fIscript\fR argument is specified, then \fBfileevent\fR
creates a new event handler: \fIscript\fR will be evaluated
whenever the channel becomes readable or writable (depending on the
@@ -102,7 +107,7 @@ buggy handlers.
by Mark Diekhans.
.SH "SEE ALSO"
-bgerror(n), fconfigure(n), gets(n), puts(n), read(n)
+bgerror(n), fconfigure(n), gets(n), puts(n), read(n), Tcl_StandardChannels(3)
.SH KEYWORDS
asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
diff --git a/doc/flush.n b/doc/flush.n
index 8fb87f6..172555c 100644
--- a/doc/flush.n
+++ b/doc/flush.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: flush.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: flush.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH flush n 7.5 Tcl "Tcl Built-In Commands"
@@ -20,8 +20,15 @@ flush \- Flush buffered output for a channel
.SH DESCRIPTION
.PP
Flushes any output that has been buffered for \fIchannelId\fR.
-\fIChannelId\fR must be a channel identifier such as returned by a previous
-\fBopen\fR or \fBsocket\fR command, and it must have been opened for writing.
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return
+value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
+of a channel creation command provided by a Tcl extension. The
+channel must have been opened for writing.
+.VE
+.PP
If the channel is in blocking mode the command does not return until all the
buffered output has been flushed to the channel. If the channel is in
nonblocking mode, the command may return before all buffered output has been
@@ -29,7 +36,7 @@ flushed; the remainder will be flushed in the background as fast as the
underlying file or device is able to absorb it.
.SH "SEE ALSO"
-file(n), open(n), socket(n)
+file(n), open(n), socket(n), Tcl_StandardChannels(3)
.SH KEYWORDS
blocking, buffer, channel, flush, nonblocking, output
diff --git a/doc/gets.n b/doc/gets.n
index e88c2ae..f884d11 100644
--- a/doc/gets.n
+++ b/doc/gets.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: gets.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: gets.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH gets n 7.5 Tcl "Tcl Built-In Commands"
@@ -22,6 +22,15 @@ gets \- Read a line from a channel
This command reads the next line from \fIchannelId\fR, returns everything
in the line up to (but not including) the end-of-line character(s), and
discards the end-of-line character(s).
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as the
+Tcl standard input channel (\fBstdin\fR), the return value from an
+invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel
+creation command provided by a Tcl extension. The channel must have
+been opened for input.
+.VE
+.PP
If \fIvarName\fR is omitted the line is returned as the result of the
command.
If \fIvarName\fR is specified then the line is placed in the variable by
@@ -44,7 +53,7 @@ The \fBeof\fR and \fBfblocked\fR commands can be used to distinguish
these three cases.
.SH "SEE ALSO"
-file(n), eof(n), fblocked(n)
+file(n), eof(n), fblocked(n), Tcl_StandardChannels(3)
.SH KEYWORDS
blocking, channel, end of file, end of line, line, nonblocking, read
diff --git a/doc/puts.n b/doc/puts.n
index 8ea9708..9a4cbdd 100644
--- a/doc/puts.n
+++ b/doc/puts.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: puts.n,v 1.4 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: puts.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH puts n 7.5 Tcl "Tcl Built-In Commands"
@@ -21,9 +21,16 @@ puts \- Write to a channel
.PP
Writes the characters given by \fIstring\fR to the channel given
by \fIchannelId\fR.
-\fIChannelId\fR must be a channel identifier such as returned from a
-previous invocation of \fBopen\fR or \fBsocket\fR. It must have been opened
-for output. If no \fIchannelId\fR is specified then it defaults to
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return
+value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
+of a channel creation command provided by a Tcl extension. The channel
+must have been opened for output.
+.VE
+.PP
+If no \fIchannelId\fR is specified then it defaults to
\fBstdout\fR. \fBPuts\fR normally outputs a newline character after
\fIstring\fR, but this feature may be suppressed by specifying the
\fB\-nonewline\fR switch.
@@ -63,7 +70,7 @@ be used in an event-driven fashion with the \fBfileevent\fR command
via a file event that the channel is ready for more output data).
.SH "SEE ALSO"
-file(n), fileevent(n)
+file(n), fileevent(n), Tcl_StandardChannels(3)
.SH KEYWORDS
channel, newline, output, write
diff --git a/doc/read.n b/doc/read.n
index 66dba85..b80f134 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: read.n,v 1.6 2001/04/06 14:27:51 dkf Exp $
+'\" RCS: @(#) $Id: read.n,v 1.7 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH read n 8.1 Tcl "Tcl Built-In Commands"
@@ -32,6 +32,14 @@ the channel is configured to use a multi-byte encoding, then the
number of characters read may not be the same as the number of bytes
read.
.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as the
+Tcl standard input channel (\fBstdin\fR), the return value from an
+invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel
+creation command provided by a Tcl extension. The channel must have
+been opened for input.
+.VE
+.PP
If \fIchannelId\fR is in nonblocking mode, the command may not read as
many characters as requested: once all available input has been read,
the command will return the data that is available rather than
@@ -50,27 +58,25 @@ which \fBfconfigure\fR will alter input.
.SH "USE WITH SERIAL PORTS"
'\" Note: this advice actually applies to many versions of Tcl
-.VS 8.4
+
For most applications a channel connected to a serial port should be
configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking
\fI0\fR. Then \fBread\fR behaves much like described above. Care
must be taken when using \fBread\fR on blocking serial ports:
.TP
\fBread \fIchannelId numChars\fR
-.
In this form \fBread\fR blocks until \fInumChars\fR have been received
from the serial port.
.TP
\fBread \fIchannelId\fR
-.
In this form \fBread\fR blocks until the reception of the end-of-file
character, see \fBfconfigure -eofchar\fR. If there no end-of-file
character has been configured for the channel, then \fBread\fR will
block forever.
-.VE
+
.SH "SEE ALSO"
-file(n), eof(n), fblocked(n), fconfigure(n)
+file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
.SH KEYWORDS
blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
diff --git a/doc/seek.n b/doc/seek.n
index 155884c..5f3118a 100644
--- a/doc/seek.n
+++ b/doc/seek.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: seek.n,v 1.4 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: seek.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH seek n 8.1 Tcl "Tcl Built-In Commands"
@@ -20,8 +20,14 @@ seek \- Change the access position for an open channel
.SH DESCRIPTION
.PP
Changes the current access position for \fIchannelId\fR.
-\fIChannelId\fR must be a channel identifier such as returned from a
-previous invocation of \fBopen\fR or \fBsocket\fR.
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
+the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
+the result of a channel creation command provided by a Tcl extension.
+.VE
+.PP
The \fIoffset\fR and \fIorigin\fR
arguments specify the position at which the next read or write will occur
for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be
@@ -58,7 +64,7 @@ not characters, unlike \fBread\fR.
.VE 8.1
.SH "SEE ALSO"
-file(n), open(n), close(n), gets(n), tell(n)
+file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3)
.SH KEYWORDS
access position, file, seek
diff --git a/doc/tell.n b/doc/tell.n
index 15cb7c1..c9475ed 100644
--- a/doc/tell.n
+++ b/doc/tell.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: tell.n,v 1.4 2000/09/07 14:27:52 poenitz Exp $
+'\" RCS: @(#) $Id: tell.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
'\"
.so man.macros
.TH tell n 8.1 Tcl "Tcl Built-In Commands"
@@ -27,9 +27,16 @@ that this value is in terms of bytes, not characters like \fBread\fR.
.VE 8.1
The value returned is -1 for channels that do not support
seeking.
+.PP
+.VS
+\fIChannelId\fR must be an identifier for an open channel such as a
+Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
+the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
+the result of a channel creation command provided by a Tcl extension.
+.VE
.SH "SEE ALSO"
-file(n), open(n), close(n), gets(n), seek(n)
+file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3)
.SH KEYWORDS
access position, channel, seeking