diff options
Diffstat (limited to 'doc/OpenFileChnl.3')
| -rw-r--r-- | doc/OpenFileChnl.3 | 72 |
1 files changed, 35 insertions, 37 deletions
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. |