diff options
author | Kevin B Kenny <kennykb@acm.org> | 2001-05-31 23:45:44 (GMT) |
---|---|---|
committer | Kevin B Kenny <kennykb@acm.org> | 2001-05-31 23:45:44 (GMT) |
commit | f16a9d29ec4b0f401338397dee7f5d24f9acffb5 (patch) | |
tree | fdd7e6cc3e4c627755440c7f60e6ebe4311248fc /doc/OpenFileChnl.3 | |
parent | 97464e6cba8eb0008cf2727c15718671992b913f (diff) | |
download | tcl-f16a9d29ec4b0f401338397dee7f5d24f9acffb5.zip tcl-f16a9d29ec4b0f401338397dee7f5d24f9acffb5.tar.gz tcl-f16a9d29ec4b0f401338397dee7f5d24f9acffb5.tar.bz2 |
Development branch for TIPs 22 and 33
kennykb_tip_22_33_botched
Diffstat (limited to 'doc/OpenFileChnl.3')
-rw-r--r-- | doc/OpenFileChnl.3 | 566 |
1 files changed, 0 insertions, 566 deletions
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 deleted file mode 100644 index e9205e3..0000000 --- a/doc/OpenFileChnl.3 +++ /dev/null @@ -1,566 +0,0 @@ -'\" -'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. -'\" -'\" 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.3 1999/04/16 00:46:32 stanton Exp $ -.so man.macros -.TH Tcl_OpenFileChannel 3 8.1 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, \- buffered I/O facilities using channels -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -typedef ... Tcl_Channel; -.sp -Tcl_Channel -\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR) -.sp -Tcl_Channel -\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) -.VS 8.0 -.sp -Tcl_Channel -\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) -.VE -.sp -Tcl_Channel -\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) -.sp -void -\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_Close\fR(\fIinterp, channel\fR) -.sp -.VS 8.1 -int -\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) -.sp -int -\fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR) -.sp -int -\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) -.sp -int -\fBTcl_Gets\fR(\fIchannel, lineRead\fR) -.sp -int -\fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) -.sp -int -\fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) -.sp -int -\fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) -.VE -.sp -int -\fBTcl_Flush\fR(\fIchannel\fR) -.sp -int -\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) -.sp -int -\fBTcl_Tell\fR(\fIchannel\fR) -.sp -int -\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) -.sp -int -\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) -.sp -int -\fBTcl_Eof\fR(\fIchannel\fR) -.sp -int -\fBTcl_InputBlocked\fR(\fIchannel\fR) -.sp -int -\fBTcl_InputBuffered\fR(\fIchannel\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelType newClientProcPtr in -.AP Tcl_Interp *interp in -Used for error reporting and to look up a channel registered in it. -.AP char *fileName in -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. -.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. -.AP int argc in -The number of elements in \fIargv\fR. -.AP char **argv in -Arguments for constructing a command pipeline. These values have the same -meaning as the non-switch arguments to the Tcl \fBexec\fR command. -.AP int flags in -Specifies the disposition of the stdio handles in pipeline: OR-ed -combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and -\fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child -in the pipe is the pipe channel, otherwise it is the same as the standard -input of the invoking process; likewise for \fBTCL_STDOUT\fR and -\fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can -redirect stdio handles to override the stdio handles for which -\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it -is set, then such redirections cause an error. -.VS 8.0 -.AP ClientData handle in -Operating system specific handle for I/O to a file. For Unix this is a -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 -The name of the channel. -.VE -.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. -.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. -.VS 8.1 br -.AP Tcl_Obj *readObjPtr in/out -A pointer to a Tcl Object in which to store the characters read from the -channel. -.AP int charsToRead in -The number of characters to read from the channel. If the channel's encoding -is \fBbinary\fR, this is equivalent to the number of bytes to read from the -channel. -.AP int appendFlag in -If non-zero, data read from the channel will be appended to the object. -Otherwise, the data will replace the existing contents of the object. -.AP char *readBuf out -A buffer in which to store the bytes read from the channel. -.AP int bytesToRead in -The number of bytes to read from the channel. The buffer \fIreadBuf\fR must -be large enough to hold this many bytes. -.AP Tcl_Obj *lineObjPtr in/out -A pointer to a Tcl object in which to store the line read from the -channel. The line read will be appended to the current value of the -object. -.AP Tcl_DString *lineRead in/out -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. -.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 -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 -output to the channel. -.VE -.AP int offset in -How far to move the access point in the channel at which the next input or -output operation will be applied, measured in bytes from the position -given by \fIseekMode\fR. May be either positive or negative. -.AP int seekMode in -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 -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 -New value for the option given by \fIoptionName\fR. -.BE - -.SH DESCRIPTION -.PP -The Tcl channel mechanism provides a device-independent and -platform-independent mechanism for performing buffered input -and output operations on a variety of file, socket, and device -types. -The channel mechanism is extensible to new channel types, by -providing a low level channel driver for the new type; the channel driver -interface is described in the manual entry for \fBTcl_CreateChannel\fR. The -channel mechanism provides a buffering scheme modeled after -Unix's standard I/O, and it also allows for nonblocking I/O on -channels. -.PP -The procedures described in this manual entry comprise the C APIs of the -generic layer of the channel architecture. For a description of the channel -driver architecture and how to implement channel drivers for new types of -channels, see the manual entry for \fBTcl_CreateChannel\fR. - -.SH TCL_OPENFILECHANNEL -.PP -\fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and -returns a channel handle that can be used to perform input and output on -the file. This API is modeled after the \fBfopen\fR procedure of -the Unix standard I/O library. -The syntax and meaning of all arguments is similar to those -given in the Tcl \fBopen\fR command when opening a file. -If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR -returns NULL and records a POSIX error code that can be -retrieved with \fBTcl_GetErrno\fR. -In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR -leaves an error message in \fIinterp\fR's result after any error. -.PP -The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. -If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it as a -replacement for the standard channel. - -.SH TCL_OPENCOMMANDCHANNEL -.PP -\fBTcl_OpenCommandChannel\fR provides a C-level interface to the -functions of the \fBexec\fR and \fBopen\fR commands. -It creates a sequence of subprocesses specified -by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can -be used to communicate with these subprocesses. -The \fIflags\fR argument indicates what sort of communication will -exist with the command pipeline. -.PP -If the \fBTCL_STDIN\fR flag is set then the standard input for the -first subprocess will be tied to the channel: writing to the channel -will provide input to the subprocess. If \fBTCL_STDIN\fR is not set, -then standard input for the first subprocess will be the same as this -application's standard input. If \fBTCL_STDOUT\fR is set then -standard output from the last subprocess can be read from the channel; -otherwise it goes to this application's standard output. If -\fBTCL_STDERR\fR is set, standard error output for all subprocesses is -returned to the channel and results in an error when the channel is -closed; otherwise it goes to this application's standard error. If -\fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can -redirect the stdio handles to override \fBTCL_STDIN\fR, -\fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an -error for argc and argv to override stdio channels for which -\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set. -.PP -If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR -returns NULL and records a POSIX error code that can be retrieved with -\fBTcl_GetErrno\fR. -In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in -\fIinterp->result\fR if \fIinterp\fR is not NULL. -.PP -The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. -If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it as a -replacement for the standard channel. - -.SH TCL_MAKEFILECHANNEL -.PP -\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, -platform-specific, file handle. -The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. -If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it as a -replacement for the standard channel. - -.SH TCL_GETCHANNEL -.PP -\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 -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. - -.SH TCL_REGISTERCHANNEL -.PP -\fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible -in \fIinterp\fR. After this call, Tcl programs executing in that -interpreter can refer to the channel in input or output operations using -the name given in the call to \fBTcl_CreateChannel\fR. After this call, -the channel becomes the property of the interpreter, and the caller should -not call \fBTcl_Close\fR for the channel; the channel will be closed -automatically when it is unregistered from the interpreter. -.PP -Code executing outside of any Tcl interpreter can call -\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it -wishes to hold a reference to this channel. Subsequently, the channel can -be registered in a Tcl interpreter and it will only be closed when the -matching number of calls to \fBTcl_UnregisterChannel\fR have been made. -This allows code executing outside of any interpreter to safely hold a -reference to a channel that is also registered in a Tcl interpreter. - -.SH TCL_UNREGISTERCHANNEL -.PP -\fBTcl_UnregisterChannel\fR removes a channel from the set of channels -accessible in \fIinterp\fR. After this call, Tcl programs will no longer be -able to use the channel's name to refer to the channel in that interpreter. -If this operation removed the last registration of the channel in any -interpreter, the channel is also closed and destroyed. -.PP -Code not associated with a Tcl interpreter can call -\fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl -that it no longer holds a reference to that channel. If this is the last -reference to the channel, it will now be closed. - -.SH TCL_CLOSE -.PP -\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a -currently open channel. The channel should not be registered in any -interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to -the channel's output device prior to destroying the channel, and any -buffered input is discarded. If this is a blocking channel, the call does -not return until all buffered data is successfully sent to the channel's -output device. If this is a nonblocking channel and there is buffered -output that cannot be written without blocking, the call returns -immediately; output is flushed in the background and the channel will be -closed once all of the buffered data has been output. In this case errors -during flushing are not reported. -.PP -If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR. -If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a -POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -If the channel is being closed synchronously and an error occurs during -closing of the channel and \fIinterp\fR is not NULL, an error message is -left in \fIinterp->result\fR. -.PP -Note: it is not safe to call \fBTcl_Close\fR on a channel that has been -registered using \fBTcl_RegisterChannel\fR; see the documentation for -\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever -been given as the \fBchan\fR argument in a call to -\fBTcl_RegisterChannel\fR, you should instead use -\fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR -when all calls to \fBTcl_RegisterChannel\fR have been matched by -corresponding calls to \fBTcl_UnregisterChannel\fR. - -.VS 8.1 br -.SH TCL_READCHARS AND TCL_READ -.PP -\fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes -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 -return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that -can be retrieved with \fBTcl_GetErrno\fR. -.PP -The return value may be smaller than the value to read, indicating that less -data than requested was available. This is called a \fIshort read\fR. In -blocking mode, this can only happen on an end-of-file. In nonblocking mode, -a short read can also occur if there is not enough input currently -available: \fBTcl_ReadChars\fR returns a short count rather than waiting -for more data. -.PP -If the channel is in blocking mode, a return value of zero indicates an -end-of-file condition. If the channel is in nonblocking mode, a return -value of zero indicates either that no input is currently available or an -end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell -which of these conditions actually occurred. -.PP -\fBTcl_ReadChars\fR translates the various end-of-line representations into -the canonical \fB\en\fR internal representation according to the current -end-of-line recognition mode. End-of-line recognition and the various -platform-specific modes are described in the manual entry for the Tcl -\fBfconfigure\fR command. -.PP -As a performance optimization, when reading from a channel with the encoding -\fBbinary\fR, the bytes are not converted to UTF-8 as they are read. -Instead, they are stored in \fIreadObjPtr\fR's internal representation as a -byte-array object. The string representation of this object will only be -constructed if it is needed (e.g., because of a call to -\fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read -from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and -related functions, and then written to a channel without the expense of ever -converting to or from UTF-8. -.PP -\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do -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. -Its contents are valid from the zeroth position up to and excluding the -position indicated by the return value. - -.SH TCL_GETSOBJ AND TCL_GETS -.PP -\fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to -UTF-8 based on the channel's encoding, until a full line of input has been -seen. If the channel's encoding is \fBbinary\fR, each byte read from the -channel is treated as an individual Unicode character. All of the -characters of the line except for the terminating end-of-line character(s) -are appended to \fIlineObjPtr\fR's string representation. The end-of-line -character(s) are read and discarded. -.PP -If a line was successfully read, the return value is greater than or equal -to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an -error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code -that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also -returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure -can be used to distinguish an error from an end-of-file condition. -.PP -If the channel is in nonblocking mode, the return value can also be \-1 if -no data was available or the data that was available did not contain an -end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR -procedure may be invoked to determine if the channel is blocked because -of input unavailability. -.PP -\fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting -characters are appended to the appended to the dynamic string given by -\fIdsPtr\fR rather than a Tcl object. - -.SH TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE -.PP -\fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at -\fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the -channel's encoding and queued for output to \fIchannel\fR. If -\fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR -to be NULL terminated and it outputs everything up to the NULL. -.PP -Data queued for output may not appear on the output device immediately, due -to internal buffering. If the data should appear immediately, call -\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the -\fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data -to appear as soon as a complete line is accepted for output, set the -\fB\-buffering\fR option on the channel to \fBline\fR mode. -.PP -The return value of \fBTcl_WriteChars\fR is a count of how many bytes were -accepted for output to the channel. This is either greater than zero to -indicate success or \-1 to indicate that an error occurred. If an error -occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be -retrieved with \fBTcl_GetErrno\fR. -.PP -Newline characters in the output data are translated to platform-specific -end-of-line sequences according to the \fB\-translation\fR option for the -channel. This is done even if the channel has no encoding. -.PP -\fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it -accepts a Tcl object whose contents will be output to the channel. The -UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted -to the channel's encoding and queued for output to \fIchannel\fR. -As a performance optimization, when writing to a channel with the encoding -\fBbinary\fR, UTF-8 characters are not converted as they are written. -Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a -byte-array object are written to the channel. The byte-array representation -of the object will be constructed if it is needed. In this way, -byte-oriented data can be read from a channel, manipulated by calling -\fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a -channel without the expense of ever converting to or from UTF-8. -.PP -\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do -encoding conversions, regardless of the channel's encoding. It is -deprecated and exists for backwards compatibility with non-internationalized -Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at -\fIbyteBuf\fR and queues them for output to \fIchannel\fR. If -\fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be -NULL terminated and it outputs everything up to the NULL. -.VE - -.SH TCL_FLUSH -.PP -\fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR -to be written to its underlying file or device as soon as possible. -If the channel is in blocking mode, the call does not return until -all the buffered data has been sent to the channel or some error occurred. -The call returns immediately if the channel is nonblocking; it starts -a background flush that will write the buffered data to the channel -eventually, as fast as the channel is able to absorb it. -.PP -The return value is normally \fBTCL_OK\fR. -If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and -records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. - -.SH TCL_SEEK -.PP -\fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent -data will be read or written. Buffered output is flushed to the channel and -buffered input is discarded, prior to the seek operation. -.PP -\fBTcl_Seek\fR normally returns the new access point. -If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error -code that can be retrieved with \fBTcl_GetErrno\fR. -After an error, the access point may or may not have been moved. - -.SH TCL_TELL -.PP -\fBTcl_Tell\fR returns the current access point for a channel. The returned -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 -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. -If \fIoptionName\fR is not NULL, it is the name of the -option to query; the option's value is copied to the Tcl dynamic string -denoted by \fIoptionValue\fR. If -\fIoptionName\fR is NULL, the function stores an alternating list of option -names and their values in \fIoptionValue\fR, using a series of calls to -\fBTcl_DStringAppendElement\fR. The various preexisting options and -their possible values are described in the manual entry for the Tcl -\fBfconfigure\fR command. Other options can be added by each channel type. -These channel type specific options are described in the manual entry for -the Tcl command that creates a channel of that type; for example, the -additional options for TCP based channels are described in the manual entry -for the Tcl \fBsocket\fR command. -The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns -\fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX -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. -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 \fIinterp->result\fR. - -.SH TCL_EOF -.PP -\fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered -an end of file during the last input operation. - -.SH TCL_INPUTBLOCKED -.PP -\fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in -nonblocking mode and the last input operation returned less data than -requested because there was insufficient data available. -The call always returns zero if the channel is in blocking mode. - -.SH TCL_INPUTBUFFERED -.PP -\fBTcl_InputBuffered\fR returns the number of bytes of input currently -buffered in the internal buffers for a channel. If the channel is not open -for reading, this function always returns zero. - -.VS 8.0 -.SH "PLATFORM ISSUES" -.PP -The handles returned from \fBTcl_GetChannelHandle\fR depend on the -platform and the channel type. On Unix platforms, the handle is -always a Unix file descriptor as returned from the \fBopen\fR system -call. On Windows platforms, the handle is a file \fBHANDLE\fR when -the channel was created with \fBTcl_OpenFileChannel\fR, -\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other -channel types may return a different type of handle on Windows -platforms. On the Macintosh platform, the handle is a file reference -number as returned from \fBHOpenDF\fR. -.VE - -.SH "SEE ALSO" -DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3) - -.SH KEYWORDS -access point, blocking, buffered I/O, channel, channel driver, end of file, -flush, input, nonblocking, output, read, seek, write |