通讯编程

开发平台：
Visual C++

OpenFileChnl.3：源码内容
							'"
'" 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.20.2.4 2004/07/16 22:22:15 andreas_kupries Exp $
.so man.macros
.TH Tcl_OpenFileChannel 3 8.3 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_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, 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, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw - buffered I/O facilities using channels
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
Tcl_Channel
fBTcl_OpenFileChannelfR(fIinterp, fileName, mode, permissionsfR)
.sp
Tcl_Channel
fBTcl_OpenCommandChannelfR(fIinterp, argc, argv, flagsfR)
.sp
Tcl_Channel
fBTcl_MakeFileChannelfR(fIhandle, readOrWritefR)
.sp
Tcl_Channel
fBTcl_GetChannelfR(fIinterp, channelName, modePtrfR)
.VS 8.3
.sp
int
fBTcl_GetChannelNamesfR(fIinterpfR)
.sp
int
fBTcl_GetChannelNamesExfR(fIinterp, patternfR)
.VE
.sp
void
fBTcl_RegisterChannelfR(fIinterp, channelfR)
.sp
int
fBTcl_UnregisterChannelfR(fIinterp, channelfR)
.sp
int
fBTcl_DetachChannelfR(fIinterp, channelfR)
.sp
int
fBTcl_IsStandardChannelfR(fIchannelfR)
.sp
int
fBTcl_ClosefR(fIinterp, channelfR)
.sp
.VS 8.1
int
fBTcl_ReadCharsfR(fIchannel, readObjPtr, charsToRead, appendFlagfR)
.sp
int
fBTcl_ReadfR(fIchannel, readBuf, bytesToReadfR)
.sp
int
fBTcl_GetsObjfR(fIchannel, lineObjPtrfR)
.sp
int
fBTcl_GetsfR(fIchannel, lineReadfR)
.sp
int
fBTcl_UngetsfR(fIchannel, input, inputLen, addAtEndfR)
.sp
int
fBTcl_WriteObjfR(fIchannel, writeObjPtrfR)
.sp
int
fBTcl_WriteCharsfR(fIchannel, charBuf, bytesToWritefR)
.sp
int
fBTcl_WritefR(fIchannel, byteBuf, bytesToWritefR)
.VE
.VS 8.3.2
.sp
int
fBTcl_ReadRawfR(fIchannel, readBuf, bytesToReadfR)
.sp
int
fBTcl_WriteRawfR(fIchannel, byteBuf, bytesToWritefR)
.VE
.sp
int
fBTcl_EoffR(fIchannelfR)
.sp
int
fBTcl_FlushfR(fIchannelfR)
.sp
int
fBTcl_InputBlockedfR(fIchannelfR)
.sp
int
fBTcl_InputBufferedfR(fIchannelfR)
.VS 8.4
.sp
int
fBTcl_OutputBufferedfR(fIchannelfR)
.VE
.sp
.VS 8.4
Tcl_WideInt
fBTcl_SeekfR(fIchannel, offset, seekModefR)
.sp
Tcl_WideInt
fBTcl_TellfR(fIchannelfR)
.VE 8.4
.sp
int
fBTcl_GetChannelOptionfR(fIinterp, channel, optionName, optionValuefR)
.sp
int
fBTcl_SetChannelOptionfR(fIinterp, channel, optionName, newValuefR)
.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 "CONST char" *fileName in
The name of a local or network file.
.AP "CONST char" *mode in
Specifies how the file is to be accessed.  May have any of the values
allowed for the fImodefR argument to the Tcl fBopenfR 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.
.AP int argc in
The number of elements in fIargvfR.
.AP "CONST char" **argv in
Arguments for constructing a command pipeline.  These values have the same
meaning as the non-switch arguments to the Tcl fBexecfR command.
.AP int flags in
Specifies the disposition of the stdio handles in pipeline: OR-ed
combination of fBTCL_STDINfR, fBTCL_STDOUTfR, fBTCL_STDERRfR, and
fBTCL_ENFORCE_MODEfR. If fBTCL_STDINfR 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_STDOUTfR and
fBTCL_STDERRfR. If fBTCL_ENFORCE_MODEfR is not set, then the pipe can
redirect stdio handles to override the stdio handles for which
fBTCL_STDINfR, fBTCL_STDOUTfR and fBTCL_STDERRfR have been set.  If it
is set, then such redirections cause an error.
.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_READABLEfR and fBTCL_WRITABLEfR to indicate
what operations are valid on fIhandlefR.
.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_READABLEfR and fBTCL_WRITABLEfR 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_OpenFileChannelfR.
.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 fBbinaryfR, 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 fIreadBuffR 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.
.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 "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 fIcharBuffR or fIbyteBuffR and
output to the channel.
.VE
.AP Tcl_WideInt 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 fIseekModefR.  May be either positive or negative.
.AP int seekMode in
Relative to which point to seek; used with fIoffsetfR to calculate the new
access point for the channel. Legal values are fBSEEK_SETfR,
fBSEEK_CURfR, and fBSEEK_ENDfR.
.AP "CONST char" *optionName in
The name of an option applicable to this channel, such as fB-blockingfR.
May have any of the values accepted by the fBfconfigurefR 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 "CONST char" *newValue in
New value for the option given by fIoptionNamefR.
.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_CreateChannelfR. 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_CreateChannelfR.
.SH TCL_OPENFILECHANNEL
.PP
fBTcl_OpenFileChannelfR opens a file specified by fIfileNamefR and
returns a channel handle that can be used to perform input and output on
the file. This API is modeled after the fBfopenfR procedure of
the Unix standard I/O library.
The syntax and meaning of all arguments is similar to those
given in the Tcl fBopenfR command when opening a file.
If an error occurs while opening the channel, fBTcl_OpenFileChannelfR
returns NULL and records a POSIX error code that can be
retrieved with fBTcl_GetErrnofR.
In addition, if fIinterpfR is non-NULL, fBTcl_OpenFileChannelfR
leaves an error message in fIinterpfR's result after any error.  
As of Tcl 8.4, the object-based API fBTcl_FSOpenFileChannelfR should 
be used in preference to fBTcl_OpenFileChannelfR wherever possible.
.PP
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use fBTcl_RegisterChannelfR, described below.
If one of the standard channels, fBstdin, stdoutfR or fBstderrfR 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_OpenCommandChannelfR provides a C-level interface to the
functions of the fBexecfR and fBopenfR commands.
It creates a sequence of subprocesses specified
by the fIargvfR and fIargcfR arguments and returns a channel that can
be used to communicate with these subprocesses.
The fIflagsfR argument indicates what sort of communication will
exist with the command pipeline.
.PP
If the fBTCL_STDINfR 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_STDINfR is not set,
then standard input for the first subprocess will be the same as this
application's standard input.  If fBTCL_STDOUTfR 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_STDERRfR 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_MODEfR is not set, then fIargcfR and fIargvfR can
redirect the stdio handles to override fBTCL_STDINfR,
fBTCL_STDOUTfR, and fBTCL_STDERRfR; if it is set, then it is an
error for argc and argv to override stdio channels for which
fBTCL_STDINfR, fBTCL_STDOUTfR, and fBTCL_STDERRfR have been set.
.PP
If an error occurs while opening the channel, fBTcl_OpenCommandChannelfR
returns NULL and records a POSIX error code that can be retrieved with
fBTcl_GetErrnofR.
In addition, fBTcl_OpenCommandChannelfR leaves an error message in
the interpreter's result if fIinterpfR is not NULL.
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use fBTcl_RegisterChannelfR, described below.
If one of the standard channels, fBstdin, stdoutfR or fBstderrfR 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_MakeFileChannelfR makes a fBTcl_ChannelfR from an existing,
platform-specific, file handle.
The newly created channel is not registered in the supplied interpreter; to
register it, use fBTcl_RegisterChannelfR, described below.
If one of the standard channels, fBstdin, stdoutfR or fBstderrfR 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_GetChannelfR returns a channel given the fIchannelNamefR used to
create it with fBTcl_CreateChannelfR and a pointer to a Tcl interpreter in
fIinterpfR. If a channel by that name is not registered in that interpreter,
the procedure returns NULL. If the fImodePtrfR argument is not NULL, it
points at an integer variable that will receive an OR-ed combination of
fBTCL_READABLEfR and fBTCL_WRITABLEfR describing whether the channel is
open for reading and writing.
.PP
fBTcl_GetChannelNamesfR and fBTcl_GetChannelNamesExfR write the
names of the registered channels to the interpreter's result as a
list object.  fBTcl_GetChannelNamesExfR will filter these names
according to the fIpatternfR.  If fIpatternfR is NULL, then it
will not do any filtering.  The return value is fBTCL_OKfR if no
errors occurred writing to the result, otherwise it is fBTCL_ERRORfR,
and the error message is left in the interpreter's result.
.SH TCL_REGISTERCHANNEL
.PP
fBTcl_RegisterChannelfR adds a channel to the set of channels accessible
in fIinterpfR. 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_CreateChannelfR.  After this call,
the channel becomes the property of the interpreter, and the caller should
not call fBTcl_ClosefR 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_RegisterChannelfR with fIinterpfR 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_UnregisterChannelfR 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.
.PP
This procedure interacts with the code managing the standard
channels. If no standard channels were initialized before the first
call to fBTcl_RegisterChannelfR they will get initialized by that
call. See fBTcl_StandardChannelsfR for a general treatise about
standard channels and the behaviour of the Tcl library with regard to
them.
.SH TCL_UNREGISTERCHANNEL
.PP
fBTcl_UnregisterChannelfR removes a channel from the set of channels
accessible in fIinterpfR. 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_UnregisterChannelfR with fIinterpfR 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.  fBTcl_UnregisterChannelfR
is very similar to fBTcl_DetachChannelfR except that it will also
close the channel if no further references to it exist.
.SH TCL_DETACHCHANNEL
.PP
fBTcl_DetachChannelfR removes a channel from the set of channels
accessible in fIinterpfR. After this call, Tcl programs will no longer be
able to use the channel's name to refer to the channel in that interpreter.
Beyond that, this command has no further effect.  It cannot be used on
the standard channels (stdout, stderr, stdin), and will return
TCL_ERROR if passed one of those channels.
.PP
Code not associated with a Tcl interpreter can call
fBTcl_DetachChannelfR with fIinterpfR 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, unlike fBTcl_UnregisterChannelfR, 
it will not be closed.
.SH TCL_ISSTANDARDCHANNEL
.PP
fBTcl_IsStandardChannelfR tests whether a channel is one of the
three standard channels, stdin, stdout or stderr.  If so, it returns
1, otherwise 0.
.PP
No attempt is made to check whether the given channel or the standard 
channels are initialized or otherwise valid.
.SH TCL_CLOSE
.PP
fBTcl_ClosefR destroys the channel fIchannelfR, which must denote a
currently open channel. The channel should not be registered in any
interpreter when fBTcl_ClosefR 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_ClosefR returns fBTCL_OKfR.
If an error occurs, fBTcl_ClosefR returns fBTCL_ERRORfR and records a
POSIX error code that can be retrieved with fBTcl_GetErrnofR.
If the channel is being closed synchronously and an error occurs during
closing of the channel and fIinterpfR is not NULL, an error message is
left in the interpreter's result.
.PP
Note: it is not safe to call fBTcl_ClosefR on a channel that has been
registered using fBTcl_RegisterChannelfR; see the documentation for
fBTcl_RegisterChannelfR, above, for details. If the channel has ever
been given as the fBchanfR argument in a call to
fBTcl_RegisterChannelfR, you should instead use
fBTcl_UnregisterChannelfR, which will internally call fBTcl_ClosefR
when all calls to fBTcl_RegisterChannelfR have been matched by
corresponding calls to fBTcl_UnregisterChannelfR.
.VS 8.1 br
.SH "TCL_READCHARS AND TCL_READ"
.PP
fBTcl_ReadCharsfR consumes bytes from fIchannelfR, converting the bytes
to UTF-8 based on the channel's encoding and storing the produced data in 
fIreadObjPtrfR's string representation.  The return value of
fBTcl_ReadCharsfR is the number of characters, up to fIcharsToReadfR,
that were stored in fIreadObjPtrfR.  If an error occurs while reading, the
return value is -1 and fBTcl_ReadCharsfR records a POSIX error code that
can be retrieved with fBTcl_GetErrnofR.
.PP
Setting fIcharsToReadfR to fB-1fR will cause the command to read
all characters currently available (non-blocking) or everything until
eof (blocking mode).
.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 readfR.  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_ReadCharsfR 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_EoffR and fBTcl_InputBlockedfR to tell
which of these conditions actually occurred.
.PP
fBTcl_ReadCharsfR translates the various end-of-line representations into
the canonical fBenfR 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
fBfconfigurefR command.
.PP
As a performance optimization, when reading from a channel with the encoding
fBbinaryfR, the bytes are not converted to UTF-8 as they are read.
Instead, they are stored in fIreadObjPtrfR'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_GetStringFromObjfR).  In this way, byte-oriented data can be read
from a channel, manipulated by calling fBTcl_GetByteArrayFromObjfR and
related functions, and then written to a channel without the expense of ever
converting to or from UTF-8.
.PP
fBTcl_ReadfR is similar to fBTcl_ReadCharsfR, 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 fIchannelfR and stores them in
fIreadBuffR, performing end-of-line translations on the way.  The return value
of fBTcl_ReadfR is the number of bytes, up to fIbytesToReadfR, written in
fIreadBuffR.  The buffer produced by fBTcl_ReadfR is not null-terminated.
Its contents are valid from the zeroth position up to and excluding the
position indicated by the return value.  
.PP
fBTcl_ReadRawfR is the same as fBTcl_ReadfR but does not
compensate for stacking. While fBTcl_ReadfR (and the other functions
in the API) always get their data from the topmost channel in the
stack the supplied channel is part of, fBTcl_ReadRawfR does
not. Thus this function is fBonlyfR usable for transformational
channel drivers, i.e. drivers used in the middle of a stack of
channels, to move data from the channel below into the transformation.
.SH "TCL_GETSOBJ AND TCL_GETS"
.PP
fBTcl_GetsObjfR consumes bytes from fIchannelfR, 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 fBbinaryfR, 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 fIlineObjPtrfR'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 fIlineObjPtrfR.  If an
error occurs, fBTcl_GetsObjfR returns -1 and records a POSIX error code
that can be retrieved with fBTcl_GetErrnofR.  fBTcl_GetsObjfR also
returns -1 if the end of the file is reached; the fBTcl_EoffR 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_InputBlockedfR
procedure may be invoked to determine if the channel is blocked because
of input unavailability.
.PP
fBTcl_GetsfR is the same as fBTcl_GetsObjfR except the resulting
characters are appended to the dynamic string given by
fIlineReadfR rather than a Tcl object.
.SH "TCL_UNGETS"
.PP
fBTcl_UngetsfR is used to add data to the input queue of a channel,
at either the head or tail of the queue.  The pointer fIinputfR points
to the data that is to be added.  The length of the input to add is given
by fIinputLenfR.  A non-zero value of fIaddAtEndfR 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 fIchannelfR has a "sticky" EOF set, no data will be
added to the input queue.  fBTcl_UngetsfR returns fIinputLenfR or
-1 if an error occurs.
.SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
.PP
fBTcl_WriteCharsfR accepts fIbytesToWritefR bytes of character data at
fIcharBuffR.  The UTF-8 characters in the buffer are converted to the
channel's encoding and queued for output to fIchannelfR.  If
fIbytesToWritefR is negative, fBTcl_WriteCharsfR expects fIcharBuffR
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_FlushfR after the call to fBTcl_WriteCharsfR, or set the 
fB-bufferingfR option on the channel to fBnonefR.  If you wish the data
to appear as soon as a complete line is accepted for output, set the
fB-bufferingfR option on the channel to fBlinefR mode.
.PP
The return value of fBTcl_WriteCharsfR 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_WriteCharsfR records a POSIX error code that may be
retrieved with fBTcl_GetErrnofR.
.PP
Newline characters in the output data are translated to platform-specific
end-of-line sequences according to the fB-translationfR option for the
channel.  This is done even if the channel has no encoding.
.PP
fBTcl_WriteObjfR is similar to fBTcl_WriteCharsfR except it
accepts a Tcl object whose contents will be output to the channel.  The
UTF-8 characters in fIwriteObjPtrfR's string representation are converted
to the channel's encoding and queued for output to fIchannelfR.  
As a performance optimization, when writing to a channel with the encoding
fBbinaryfR, UTF-8 characters are not converted as they are written.
Instead, the bytes in fIwriteObjPtrfR'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_GetByteArrayFromObjfR and related functions, and then written to a
channel without the expense of ever converting to or from UTF-8.
.PP
fBTcl_WritefR is similar to fBTcl_WriteCharsfR 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 fIbytesToWritefR bytes of data at
fIbyteBuffR and queues them for output to fIchannelfR.  If
fIbytesToWritefR is negative, fBTcl_WritefR expects fIbyteBuffR to be
null-terminated and it outputs everything up to the null.
.PP
fBTcl_WriteRawfR is the same as fBTcl_WritefR but does not
compensate for stacking. While fBTcl_WritefR (and the other
functions in the API) always feed their input to the topmost channel
in the stack the supplied channel is part of, fBTcl_WriteRawfR does
not. Thus this function is fBonlyfR usable for transformational
channel drivers, i.e. drivers used in the middle of a stack of
channels, to move data from the transformation into the channel below
it.
.VE
.SH TCL_FLUSH
.PP
fBTcl_FlushfR causes all of the buffered output data for fIchannelfR
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_OKfR.
If an error occurs, fBTcl_FlushfR returns fBTCL_ERRORfR and
records a POSIX error code that can be retrieved with fBTcl_GetErrnofR.
.SH TCL_SEEK
.PP
fBTcl_SeekfR moves the access point in fIchannelfR 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_SeekfR normally returns the new access point.
If an error occurs, fBTcl_SeekfR returns -1 and records a POSIX error
code that can be retrieved with fBTcl_GetErrnofR.
After an error, the access point may or may not have been moved.
.SH TCL_TELL
.PP
fBTcl_TellfR 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_GetChannelOptionfR retrieves, in fIoptionValuefR, the value of one of
the options currently in effect for a channel, or a list of all options and
their values.  The fIchannelfR argument identifies the channel for which
to query an option or retrieve all options and their values.
If fIoptionNamefR 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 fIoptionValuefR. If
fIoptionNamefR is NULL, the function stores an alternating list of option
names and their values in fIoptionValuefR, using a series of calls to
fBTcl_DStringAppendElementfR. The various preexisting options and
their possible values are described in the manual entry for the Tcl
fBfconfigurefR 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 fBsocketfR command.
The procedure normally returns fBTCL_OKfR. If an error occurs, it returns
fBTCL_ERRORfR and calls fBTcl_SetErrnofR to store an appropriate POSIX
error code.
.SH TCL_SETCHANNELOPTION
.PP
fBTcl_SetChannelOptionfR sets a new value fInewValuefR
for an option fIoptionNamefR on fIchannelfR.
The procedure normally returns fBTCL_OKfR.  If an error occurs,
it returns fBTCL_ERRORfR;  in addition, if fIinterpfR is non-NULL,
fBTcl_SetChannelOptionfR leaves an error message in the interpreter's result.
.SH TCL_EOF
.PP
fBTcl_EoffR returns a nonzero value if fIchannelfR encountered
an end of file during the last input operation.
.SH TCL_INPUTBLOCKED
.PP
fBTcl_InputBlockedfR returns a nonzero value if fIchannelfR 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_InputBufferedfR 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.
.SH TCL_OUTPUTBUFFERED
.VS 8.4
fBTcl_OutputBufferedfR returns the number of bytes of output
currently buffered in the internal buffers for a channel. If the
channel is not open for writing, this function always returns zero.
.VE
.SH "PLATFORM ISSUES"
.PP
The handles returned from fBTcl_GetChannelHandlefR depend on the
platform and the channel type.  On Unix platforms, the handle is
always a Unix file descriptor as returned from the fBopenfR system
call.  On Windows platforms, the handle is a file fBHANDLEfR when
the channel was created with fBTcl_OpenFileChannelfR,
fBTcl_OpenCommandChannelfR, or fBTcl_MakeFileChannelfR.  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 fBHOpenDFfR.
.SH "SEE ALSO"
DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
.SH KEYWORDS
access point, blocking, buffered I/O, channel, channel driver, end of file,
flush, input, nonblocking, output, read, seek, write

						