diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CrtChannel.3 | 47 | ||||
| -rw-r--r-- | doc/OpenFileChnl.3 | 72 |
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. |