summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2002-01-15 17:55:29 (GMT)
committerdgp <dgp@users.sourceforge.net>2002-01-15 17:55:29 (GMT)
commit722d3186397220e0bcd65b0e0bd4ba3b91ef5534 (patch)
tree1b8e5662ba53f74c7365043b21833a6534056f98 /doc
parent0ff232587e3c63cf969da0859335adb56f4efdfd (diff)
downloadtcl-722d3186397220e0bcd65b0e0bd4ba3b91ef5534.zip
tcl-722d3186397220e0bcd65b0e0bd4ba3b91ef5534.tar.gz
tcl-722d3186397220e0bcd65b0e0bd4ba3b91ef5534.tar.bz2
* Updated APIs in the file generic/tclIO.c according to the guidelines
of TIP 27. Several minor documentation corrections as well. * Updated channel driver interface according to the guidelines of TIP 27. See also [Bug 500348]. * Moved Tcl_EolTranslation enum declaration from generic/tcl.h to generic/tclInt.h (renamed to TclEolTranslation). It is not used anywhere in Tcl's public interface.
Diffstat (limited to 'doc')
-rw-r--r--doc/CrtChannel.347
-rw-r--r--doc/OpenFileChnl.372
2 files changed, 57 insertions, 62 deletions
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 3ca35b5..1f809bc 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -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: CrtChannel.3,v 1.12 2001/12/10 15:50:46 dgp Exp $
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.13 2002/01/15 17:55:29 dgp Exp $
.so man.macros
.TH Tcl_CreateChannel 3 8.3 Tcl "Tcl Library Procedures"
.BS
@@ -25,7 +25,7 @@ ClientData
Tcl_ChannelType *
\fBTcl_GetChannelType\fR(\fIchannel\fR)
.sp
-char *
+CONST char *
\fBTcl_GetChannelName\fR(\fIchannel\fR)
.sp
int
@@ -73,7 +73,7 @@ int
Tcl_Channel
\fBTcl_GetTopChannel\fR(\fIchannel\fR)
.sp
-char *
+CONST char *
\fBTcl_ChannelName\fR(\fItypePtr\fR)
.sp
Tcl_ChannelTypeVersion
@@ -117,11 +117,11 @@ Tcl_DriverHandlerProc *
.VE
.sp
.SH ARGUMENTS
-.AS Tcl_EolTranslation *channelName in
+.AS Tcl_ChannelType *channelName in
.AP Tcl_ChannelType *typePtr in
Points to a structure containing the addresses of procedures that
can be called to perform I/O and other functions on the channel.
-.AP char *channelName in
+.AP "CONST char" *channelName in
The name of this channel, such as \fBfile3\fR; must not be in use
by any other channel. Can be NULL, in which case the channel is
created without a name.
@@ -139,9 +139,6 @@ means the output handle is wanted.
.AP ClientData *handlePtr out
Points to the location where the desired OS-specific handle should be
stored.
-.AP Tcl_EolTranslation transMode in
-The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR,
-\fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR.
.AP int size in
The size, in bytes, of buffers to allocate in this channel.
.AP int mask in
@@ -150,9 +147,9 @@ and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
this channel.
.AP Tcl_Interp *interp in
Current interpreter. (can be NULL)
-.AP char *optionName in
+.AP "CONST char" *optionName in
Name of the invalid option.
-.AP char *optionList in
+.AP "CONST char" *optionList in
Specific options list (space separated words, without "-")
to append to the standard generic options list.
Can be NULL for generic options error message only.
@@ -247,7 +244,7 @@ and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
and output.
.PP
\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
-allocated to store input or output in \fIchan\fR. If the value was not set
+allocated to store input or output in \fIchannel\fR. If the value was not set
by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
the default value of 4096 is returned.
.PP
@@ -301,7 +298,7 @@ is not allowed.
Application to a channel registered in some interpreter is not allowed.
.PP
\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event
-scripts associated with the specified \fIchannels\fR, thus shutting
+scripts associated with the specified \fIchannel\fR, thus shutting
down all event processing for this channel.
.VE
@@ -528,7 +525,7 @@ generic layer to transfer data from an internal buffer to the output device.
.CS
typedef int Tcl_DriverOutputProc(
ClientData \fIinstanceData\fR,
- char *\fIbuf\fR,
+ CONST char *\fIbuf\fR,
int \fItoWrite\fR,
int *\fIerrorCodePtr\fR);
.CE
@@ -604,11 +601,11 @@ the generic layer to set a channel type specific option on a channel.
typedef int Tcl_DriverSetOptionProc(
ClientData \fIinstanceData\fR,
Tcl_Interp *\fIinterp\fR,
- char *\fIoptionName\fR,
- char *\fIoptionValue\fR);
+ CONST char *\fIoptionName\fR,
+ CONST char *\fInewValue\fR);
.CE
.PP
-\fIoptionName\fR is the name of an option to set, and \fIoptionValue\fR is
+\fIoptionName\fR is the name of an option to set, and \fInewValue\fR is
the new value for that option, as a string. The \fIinstanceData\fR is the
same as the value given to \fBTcl_CreateChannel\fR when this channel was
created. The function should do whatever channel type specific action is
@@ -626,7 +623,7 @@ returns \fBTCL_OK\fR.
It should call \fBTcl_BadChannelOption\fR which itself returns
\fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized.
-If \fIoptionValue\fR specifies a value for the option that
+If \fInewValue\fR specifies a value for the option that
is not supported or if a system call error occurs,
the function should leave an error message in the
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
@@ -648,21 +645,21 @@ channel. \fIgetOptionProc\fR must match the following prototype:
typedef int Tcl_DriverGetOptionProc(
ClientData \fIinstanceData\fR,
Tcl_Interp *\fIinterp\fR,
- char *\fIoptionName\fR,
- Tcl_DString *\fIdsPtr\fR);
+ CONST char *\fIoptionName\fR,
+ Tcl_DString *\fIoptionValue\fR);
.CE
.PP
\fIOptionName\fR is the name of an option supported by this type of
channel. If the option name is not NULL, the function stores its current
-value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
-If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
+value, as a string, in the Tcl dynamic string \fIoptionValue\fR.
+If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an
alternating list of all supported options and their current values.
On success, the function returns \fBTCL_OK\fR.
It should call \fBTcl_BadChannelOption\fR which itself returns
\fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized. If a system call error occurs,
the function should leave an error message in the
-\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
+result of \fIinterp\fR if \fIinterp\fR is not NULL. The
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.
.PP
@@ -793,7 +790,7 @@ the generic options error message string.
.PP
It always return \fBTCL_ERROR\fR
.PP
-An error message is generated in interp's result object to
+An error message is generated in \fIinterp\fR's result object to
indicate that a command was invoked with the a bad option
The message has the form
.CS
@@ -803,9 +800,9 @@ so you get for instance:
bad option "-blah": should be one of -blocking,
-buffering, -buffersize, -eofchar, -translation,
-peername, or -sockname
-when called with optionList="peername sockname"
+when called with \fIoptionList\fR="peername sockname"
.CE
-``blah'' is the optionName argument and ``<specific options>''
+``blah'' is the \fIoptionName\fR argument and ``<specific options>''
is a space separated list of specific option words.
The function takes good care of inserting minus signs before
each option, commas after, and an ``or'' before the last option.
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index d778007..c694c45 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -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: OpenFileChnl.3,v 1.15 2001/12/10 15:50:46 dgp Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.16 2002/01/15 17:55:29 dgp Exp $
.so man.macros
.TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
.BS
@@ -15,8 +15,6 @@ Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel
.nf
\fB#include <tcl.h>\fR
.sp
-typedef ... Tcl_Channel;
-.sp
Tcl_Channel
\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
.sp
@@ -57,7 +55,7 @@ int
\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
.sp
int
-\fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR)
+\fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
.sp
int
\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
@@ -80,10 +78,10 @@ int
.VS 8.3.2
.sp
int
-\fBTcl_ReadRaw\fR(\fIchannel, bufPtr, bytesToRead\fR)
+\fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
.sp
int
-\fBTcl_WriteRaw\fR(\fIchannel, bufPtr, bytesToWrite\fR)
+\fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
.VE
.sp
int
@@ -123,8 +121,7 @@ Used for error reporting and to look up a channel registered in it.
The name of a local or network file.
.AP char *mode in
Specifies how the file is to be accessed. May have any of the values
-allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. For
-\fBTcl_OpenCommandChannel\fR, may be NULL.
+allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
.AP int permissions in
POSIX-style permission flags such as 0644. If a new file is created, these
permissions will be set on the created file.
@@ -149,12 +146,16 @@ file descriptor, for Windows it is a HANDLE.
.AP int readOrWrite in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
what operations are valid on \fIhandle\fR.
-.AP char *channelName in
+.AP "CONST char" *channelName in
The name of the channel.
.AP int *modePtr out
Points at an integer variable that will receive an OR-ed combination of
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
open for reading and writing.
+.VS 8.3
+.AP "CONST char" *pattern in
+The pattern to match on, passed to Tcl_StringMatch, or NULL.
+.VE
.AP Tcl_Channel channel in
A Tcl channel for input or output. Must have been the return value
from a procedure such as \fBTcl_OpenFileChannel\fR.
@@ -182,11 +183,20 @@ object.
A pointer to a Tcl dynamic string in which to store the line read from the
channel. Must have been initialized by the caller. The line read will be
appended to any data already in the dynamic string.
+.VS 8.3
+.AP "CONST char" *input in
+The input to add to a channel buffer.
+.AP int inputLen in
+Length of the input
+.AP int addAtEnd in
+Flag indicating whether the input should be added to the end or
+beginning of the channel buffer.
+.VE
.AP Tcl_Obj *writeObjPtr in
A pointer to a Tcl Object whose contents will be output to the channel.
.AP "CONST char" *charBuf in
A buffer containing the characters to output to the channel.
-.AP char *byteBuf in
+.AP "CONST char" *byteBuf in
A buffer containing the bytes to output to the channel.
.AP int bytesToWrite in
The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
@@ -200,25 +210,14 @@ given by \fIseekMode\fR. May be either positive or negative.
Relative to which point to seek; used with \fIoffset\fR to calculate the new
access point for the channel. Legal values are \fBSEEK_SET\fR,
\fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP char *optionName in
+.AP "CONST char" *optionName in
The name of an option applicable to this channel, such as \fB\-blocking\fR.
May have any of the values accepted by the \fBfconfigure\fR command.
.AP Tcl_DString *optionValue in
Where to store the value of an option or a list of all options and their
values. Must have been initialized by the caller.
-.AP char *newValue in
+.AP "CONST char" *newValue in
New value for the option given by \fIoptionName\fR.
-.VS 8.3
-.AP char *pattern in
-The pattern to match on, passed to Tcl_StringMatch, or NULL.
-.AP char *input in
-The input to add to a channel buffer.
-.AP int inputLen in
-Length of the input
-.AP int addToEnd in
-Flag indicating whether the input should be added to the end or
-beginning of the channel buffer.
-.VE
.BE
.SH DESCRIPTION
@@ -316,7 +315,7 @@ replacement for the standard channel.
\fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
\fIinterp\fR. If a channel by that name is not registered in that interpreter,
-the procedure returns NULL. If the \fImode\fR argument is not NULL, it
+the procedure returns NULL. If the \fImodePtr\fR argument is not NULL, it
points at an integer variable that will receive an OR-ed combination of
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
open for reading and writing.
@@ -430,7 +429,7 @@ corresponding calls to \fBTcl_UnregisterChannel\fR.
to UTF-8 based on the channel's encoding and storing the produced data in
\fIreadObjPtr\fR's string representation. The return value of
\fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
-that were stored in \fIobjPtr\fR. If an error occurs while reading, the
+that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the
return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
can be retrieved with \fBTcl_GetErrno\fR.
.PP
@@ -467,9 +466,9 @@ converting to or from UTF-8.
encoding conversions, regardless of the channel's encoding. It is deprecated
and exists for backwards compatibility with non-internationalized Tcl
extensions. It consumes bytes from \fIchannel\fR and stores them in
-\fIbuf\fR, performing end-of-line translations on the way. The return value
-of \fBTcl_Read\fR is the number of bytes, up to \fItoRead\fR, written in
-\fIbuf\fR. The buffer produced by \fBTcl_Read\fR is not NULL terminated.
+\fIreadBuf\fR, performing end-of-line translations on the way. The return value
+of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in
+\fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not NULL terminated.
Its contents are valid from the zeroth position up to and excluding the
position indicated by the return value.
.PP
@@ -506,15 +505,15 @@ of input unavailability.
.PP
\fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
characters are appended to the dynamic string given by
-\fIdsPtr\fR rather than a Tcl object.
+\fIlineRead\fR rather than a Tcl object.
.SH "TCL_UNGETS"
.PP
\fBTcl_Ungets\fR is used to add data to the input queue of a channel,
-at either the head or tail of the queue. \fIInput\fR is a pointer to
-the data that is to be added. \fIInputLen\fR gives the length of the
-input to add. \fIAddAtEnd\fR, in non-zero, indicates that the data is
-to be added at the end of queue; otherwise it will be added at the
+at either the head or tail of the queue. The pointer \fIinput\fR points
+to the data that is to be added. The length of the input to add is given
+by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the
+data is to be added at the end of queue; otherwise it will be added at the
head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be
added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or
-1 if an error occurs.
@@ -607,7 +606,7 @@ value is \-1 if the channel does not support seeking.
.SH TCL_GETCHANNELOPTION
.PP
-\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
+\fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
the options currently in effect for a channel, or a list of all options and
their values. The \fIchannel\fR argument identifies the channel for which
to query an option or retrieve all options and their values.
@@ -629,9 +628,8 @@ error code.
.SH TCL_SETCHANNELOPTION
.PP
-\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
-\fIOptionName\fR is the option to set and \fInewValue\fR is the value to
-set.
+\fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR
+for an option \fIoptionName\fR on \fIchannel\fR.
The procedure normally returns \fBTCL_OK\fR. If an error occurs,
it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
\fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result.