tcl/doc/OpenFileChnl.3

   1 '\"
   2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id$
   8 .so man.macros
   9 .TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
  10 .BS
  11 '\" Note:  do not modify the .SH NAME line immediately below!
  12 .SH NAME
  13 Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
  14 .SH SYNOPSIS
  15 .nf
  16 \fB#include <tcl.h>\fR
  17 .sp
  18 typedef ... Tcl_Channel;
  19 .sp
  20 Tcl_Channel
  21 \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
  22 .sp
  23 Tcl_Channel
  24 \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
  25 .VS
  26 .sp
  27 Tcl_Channel
  28 \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
  29 .VE
  30 .sp
  31 Tcl_Channel
  32 \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
  33 .sp
  34 void
  35 \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
  36 .sp
  37 int
  38 \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
  39 .sp
  40 int
  41 \fBTcl_Close\fR(\fIinterp, channel\fR)
  42 .sp
  43 int
  44 \fBTcl_Read\fR(\fIchannel, buf, toRead\fR)
  45 .sp
  46 int
  47 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
  48 .sp
  49 int
  50 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
  51 .sp
  52 int
  53 \fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
  54 .sp
  55 int
  56 \fBTcl_Flush\fR(\fIchannel\fR)
  57 .sp
  58 int
  59 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
  60 .sp
  61 int
  62 \fBTcl_Tell\fR(\fIchannel\fR)
  63 .sp
  64 int
  65 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
  66 .sp
  67 int
  68 \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
  69 .sp
  70 int
  71 \fBTcl_Eof\fR(\fIchannel\fR)
  72 .sp
  73 int
  74 \fBTcl_InputBlocked\fR(\fIchannel\fR)
  75 .sp
  76 int
  77 \fBTcl_InputBuffered\fR(\fIchannel\fR)
  78 .sp
  79 .SH ARGUMENTS
  80 .AS Tcl_ChannelType newClientProcPtr in
  81 .AP Tcl_Interp *interp in
  82 Used for error reporting and to look up a channel registered in it.
  83 .AP char *fileName in
  84 The name of a local or network file.
  85 .AP char *mode in
  86 Specifies how the file is to be accessed.  May have any of the
  87 values allowed for the \fImode\fR argument to the Tcl
  88 \fBopen\fR command.
  89 For \fBTcl_OpenCommandChannel\fR, may be NULL.
  90 .AP int permissions in
  91 POSIX-style permission flags such as 0644.
  92 If a new file is created, these permissions will be set on the
  93 created file.
  94 .AP int argc in
  95 The number of elements in \fIargv\fR.
  96 .AP char **argv in
  97 Arguments for constructing a command pipeline.
  98 These values have the same meaning as the non-switch arguments
  99 to the Tcl \fBexec\fR command.
 100 .AP int flags in
 101 Specifies the disposition of the stdio handles in pipeline: OR-ed
 102 combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR,
 103 and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for
 104 the first child in the pipe is the pipe channel, otherwise it is the same
 105 as the standard input of the invoking process; likewise for
 106 \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set,
 107 then the pipe can redirect stdio handles to override the stdio handles for
 108 which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
 109 If it is set, then such redirections cause an error.
 110 .VS
 111 .AP ClientData handle in
 112 Operating system specific handle for I/O to a file. For Unix this is a
 113 file descriptor, for Windows it is a HANDLE.
 114 .AP int readOrWrite in
 115 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
 116 what operations are valid on \fIhandle\fR.
 117 .VE
 118 .AP int *modePtr out
 119 Points at an integer variable that will receive an OR-ed combination of
 120 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
 121 open for reading and writing.
 122 .AP Tcl_Channel channel in
 123 A Tcl channel for input or output.  Must have been the return value
 124 from a procedure such as \fBTcl_OpenFileChannel\fR.
 125 .AP char *buf in
 126 An array of bytes in which to store channel input, or from which
 127 to read channel output.
 128 .AP int len in
 129 The length of the input or output.
 130 .AP int atEnd in
 131 If nonzero, store the input at the end of the input queue, otherwise store
 132 it at the head of the input queue.
 133 .AP int toRead in
 134 The number of bytes to read from the channel.
 135 .AP Tcl_DString *lineRead in
 136 A pointer to a Tcl dynamic string in which to store the line read from the
 137 channel.  Must have been initialized by the caller.  The line read
 138 will be appended to any data already in the dynamic string.
 139 .AP Tcl_Obj *linePtrObj in
 140 A pointer to a Tcl object in which to store the line read from the
 141 channel.  The line read will be appended to the current value of the
 142 object.
 143 .AP int toWrite in
 144 The number of bytes to read from \fIbuf\fR and output to the channel.
 145 .AP int offset in
 146 How far to move the access point in the channel at which the next input or
 147 output operation will be applied, measured in bytes from the position
 148 given by \fIseekMode\fR.  May be either positive or negative.
 149 .AP int seekMode in
 150 Relative to which point to seek; used with \fIoffset\fR to calculate the new
 151 access point for the channel. Legal values are \fBSEEK_SET\fR,
 152 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
 153 .AP char *optionName in
 154 The name of an option applicable to this channel, such as \fB\-blocking\fR.
 155 May have any of the values accepted by the \fBfconfigure\fR command.
 156 .AP Tcl_DString *optionValue in
 157 Where to store the value of an option or a list of all options and their
 158 values. Must have been initialized by the caller.
 159 .AP char *newValue in
 160 New value for the option given by \fIoptionName\fR.
 161 .BE
 162
 163 .SH DESCRIPTION
 164 .PP
 165 The Tcl channel mechanism provides a device-independent and
 166 platform-independent mechanism for performing buffered input
 167 and output operations on a variety of file, socket, and device
 168 types.
 169 The channel mechanism is extensible to new channel types, by
 170 providing a low level channel driver for the new type; the channel driver
 171 interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
 172 channel mechanism provides a buffering scheme modelled after
 173 Unix's standard I/O, and it also allows for nonblocking I/O on
 174 channels.
 175 .PP
 176 The procedures described in this manual entry comprise the C APIs of the
 177 generic layer of the channel architecture. For a description of the channel
 178 driver architecture and how to implement channel drivers for new types of
 179 channels, see the manual entry for \fBTcl_CreateChannel\fR.
 180
 181 .SH TCL_OPENFILECHANNEL
 182 .PP
 183 \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
 184 returns a channel handle that can be used to perform input and output on
 185 the file. This API is modelled after the \fBfopen\fR procedure of
 186 the Unix standard I/O library.
 187 The syntax and meaning of all arguments is similar to those
 188 given in the Tcl \fBopen\fR command when opening a file.
 189 If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
 190 returns NULL and records a POSIX error code that can be
 191 retrieved with \fBTcl_GetErrno\fR.
 192 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
 193 leaves an error message in \fIinterp->result\fR after any error.
 194 .PP
 195 The newly created channel is not registered in the supplied interpreter; to
 196 register it, use \fBTcl_RegisterChannel\fR, described below.
 197 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
 198 previously closed, the act of creating the new channel also assigns it as a
 199 replacement for the standard channel.
 200
 201 .SH TCL_OPENCOMMANDCHANNEL
 202 .PP
 203 \fBTcl_OpenCommandChannel\fR provides a C-level interface to the
 204 functions of the \fBexec\fR and \fBopen\fR commands.
 205 It creates a sequence of subprocesses specified
 206 by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
 207 be used to communicate with these subprocesses.
 208 The \fIflags\fR argument indicates what sort of communication will
 209 exist with the command pipeline.
 210 .PP
 211 If the \fBTCL_STDIN\fR flag is set then the standard input for the
 212 first subprocess will be tied to the channel: writing to the channel
 213 will provide input to the subprocess.  If \fBTCL_STDIN\fR is not set,
 214 then standard input for the first subprocess will be the same as this
 215 application's standard input.  If \fBTCL_STDOUT\fR is set then
 216 standard output from the last subprocess can be read from the channel;
 217 otherwise it goes to this application's standard output.  If
 218 \fBTCL_STDERR\fR is set, standard error output for all subprocesses is
 219 returned to the channel and results in an error when the channel is
 220 closed; otherwise it goes to this application's standard error.  If
 221 \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
 222 redirect the stdio handles to override \fBTCL_STDIN\fR,
 223 \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
 224 error for argc and argv to override stdio channels for which
 225 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
 226 .PP
 227 If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
 228 returns NULL and records a POSIX error code that can be retrieved with
 229 \fBTcl_GetErrno\fR.
 230 In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
 231 \fIinterp->result\fR if \fIinterp\fR is not NULL.
 232 .PP
 233 The newly created channel is not registered in the supplied interpreter; to
 234 register it, use \fBTcl_RegisterChannel\fR, described below.
 235 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
 236 previously closed, the act of creating the new channel also assigns it as a
 237 replacement for the standard channel.
 238
 239 .SH TCL_MAKEFILECHANNEL
 240 .PP
 241 \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
 242 platform-specific, file handle.
 243 The newly created channel is not registered in the supplied interpreter; to
 244 register it, use \fBTcl_RegisterChannel\fR, described below.
 245 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
 246 previously closed, the act of creating the new channel also assigns it as a
 247 replacement for the standard channel.
 248
 249 .SH TCL_GETCHANNEL
 250 .PP
 251 \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
 252 create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
 253 \fIinterp\fR. If a channel by that name is not registered in that interpreter,
 254 the procedure returns NULL. If the \fImode\fR argument is not NULL, it
 255 points at an integer variable that will receive an OR-ed combination of
 256 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
 257 open for reading and writing.
 258
 259 .SH TCL_REGISTERCHANNEL
 260 .PP
 261 \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
 262 in \fIinterp\fR. After this call, Tcl programs executing in that
 263 interpreter can refer to the channel in input or output operations using
 264 the name given in the call to \fBTcl_CreateChannel\fR.  After this call,
 265 the channel becomes the property of the interpreter, and the caller should
 266 not call \fBTcl_Close\fR for the channel; the channel will be closed
 267 automatically when it is unregistered from the interpreter.
 268 .PP
 269 Code executing outside of any Tcl interpreter can call
 270 \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
 271 wishes to hold a reference to this channel. Subsequently, the channel can
 272 be registered in a Tcl interpreter and it will only be closed when the
 273 matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
 274 This allows code executing outside of any interpreter to safely hold a
 275 reference to a channel that is also registered in a Tcl interpreter.
 276
 277 .SH TCL_UNREGISTERCHANNEL
 278 .PP
 279 \fBTcl_UnregisterChannel\fR removes a channel from the set of channels
 280 accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
 281 able to use the channel's name to refer to the channel in that interpreter.
 282 If this operation removed the last registration of the channel in any
 283 interpreter, the channel is also closed and destroyed.
 284 .PP
 285 Code not associated with a Tcl interpreter can call
 286 \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
 287 that it no longer holds a reference to that channel. If this is the last
 288 reference to the channel, it will now be closed.
 289
 290 .SH TCL_CLOSE
 291 .PP
 292 \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
 293 currently open channel. The channel should not be registered in any
 294 interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
 295 the channel's output device prior to destroying the channel, and any
 296 buffered input is discarded.  If this is a blocking channel, the call does
 297 not return until all buffered data is successfully sent to the channel's
 298 output device.  If this is a nonblocking channel and there is buffered
 299 output that cannot be written without blocking, the call returns
 300 immediately; output is flushed in the background and the channel will be
 301 closed once all of the buffered data has been output.  In this case errors
 302 during flushing are not reported.
 303 .PP
 304 If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
 305 If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
 306 POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
 307 If the channel is being closed synchronously and an error occurs during
 308 closing of the channel and \fIinterp\fR is not NULL, an error message is
 309 left in \fIinterp->result\fR.
 310 .PP
 311 Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
 312 registered using \fBTcl_RegisterChannel\fR; see the documentation for
 313 \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
 314 given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
 315 you should instead use \fBTcl_UnregisterChannel\fR, which will internally
 316 call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
 317 matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
 318
 319 .SH TCL_READ
 320 .PP
 321 \fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from
 322 \fIchannel\fR and stores it at \fIbuf\fR.
 323 The return value of \fBTcl_Read\fR is the number of characters written
 324 at \fIbuf\fR.
 325 The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents
 326 are valid from the zeroth position up to and excluding the position
 327 indicated by the return value.
 328 If an error occurs, the return value is -1 and \fBTcl_Read\fR records
 329 a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
 330 .PP
 331 The return value may be smaller than the value of \fItoRead\fR, indicating
 332 that less data than requested was available, also called a \fIshort
 333 read\fR.
 334 In blocking mode, this can only happen on an end-of-file.
 335 In nonblocking mode, a short read can also occur if there is not
 336 enough input currently available:  \fBTcl_Read\fR returns a short
 337 count rather than waiting for more data.
 338 .PP
 339 If the channel is in blocking mode, a return value of zero indicates an end
 340 of file condition. If the channel is in nonblocking mode, a return value of
 341 zero indicates either that no input is currently available or an end of
 342 file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR
 343 to tell which of these conditions actually occurred.
 344 .PP
 345 \fBTcl_Read\fR translates platform-specific end-of-line representations
 346 into the canonical \fB\en\fR internal representation according to the
 347 current end-of-line recognition mode. End-of-line recognition and the
 348 various platform-specific modes are described in the manual entry for the
 349 Tcl \fBfconfigure\fR command.
 350
 351 .SH TCL_GETS AND TCL_GETSOBJ
 352 .PP
 353 \fBTcl_Gets\fR reads a line of input from a channel and appends all of
 354 the characters of the line except for the terminating end-of-line character(s)
 355 to the dynamic string given by \fIdsPtr\fR.
 356 The end-of-line character(s) are read and discarded.
 357 .PP
 358 If a line was successfully read, the return value is greater than or
 359 equal to zero, and it indicates the number of characters stored
 360 in the dynamic string.
 361 If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error
 362 code that can be retrieved with \fBTcl_GetErrno\fR.
 363 \fBTcl_Gets\fR also returns -1 if the end of the file is reached;
 364 the \fBTcl_Eof\fR procedure can be used to distinguish an error
 365 from an end-of-file condition.
 366 .PP
 367 If the channel is in nonblocking mode, the return value can also
 368 be -1 if no data was available or the data that was available
 369 did not contain an end-of-line character.
 370 When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
 371 invoked to determine if the channel is blocked because of input
 372 unavailability.
 373 .PP
 374 \fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
 375 characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
 376 dynamic string.
 377 .SH TCL_WRITE
 378 .PP
 379 \fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
 380 on \fIchannel\fR. This data may not appear on the output device
 381 immediately. If the data should appear immediately, call \fBTcl_Flush\fR
 382 after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on
 383 the channel to \fBnone\fR. If you wish the data to appear as soon as an end
 384 of line is accepted for output, set the \fB\-buffering\fR option on the
 385 channel to \fBline\fR mode.
 386 .PP
 387 The \fItoWrite\fR argument specifies how many bytes of data are provided in
 388 the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data
 389 to be NULL terminated and it outputs everything up to the NULL.
 390 .PP
 391 The return value of \fBTcl_Write\fR is a count of how many
 392 characters were accepted for output to the channel. This is either equal to
 393 \fItoWrite\fR or -1 to indicate that an error occurred.
 394 If an error occurs, \fBTcl_Write\fR also records a POSIX error code
 395 that may be retrieved with \fBTcl_GetErrno\fR.
 396 .PP
 397 Newline characters in the output data are translated to platform-specific
 398 end-of-line sequences according to the \fB\-translation\fR option for
 399 the channel.
 400
 401 .SH TCL_FLUSH
 402 .PP
 403 \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
 404 to be written to its underlying file or device as soon as possible.
 405 If the channel is in blocking mode, the call does not return until
 406 all the buffered data has been sent to the channel or some error occurred.
 407 The call returns immediately if the channel is nonblocking; it starts
 408 a background flush that will write the buffered data to the channel
 409 eventually, as fast as the channel is able to absorb it.
 410 .PP
 411 The return value is normally \fBTCL_OK\fR.
 412 If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
 413 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
 414
 415 .SH TCL_SEEK
 416 .PP
 417 \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
 418 data will be read or written. Buffered output is flushed to the channel and
 419 buffered input is discarded, prior to the seek operation.
 420 .PP
 421 \fBTcl_Seek\fR normally returns the new access point.
 422 If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error
 423 code that can be retrieved with \fBTcl_GetErrno\fR.
 424 After an error, the access point may or may not have been moved.
 425
 426 .SH TCL_TELL
 427 .PP
 428 \fBTcl_Tell\fR returns the current access point for a channel. The returned
 429 value is -1 if the channel does not support seeking.
 430
 431 .SH TCL_GETCHANNELOPTION
 432 .PP
 433 \fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
 434 the options currently in effect for a channel, or a list of all options and
 435 their values.  The \fIchannel\fR argument identifies the channel for which
 436 to query an option or retrieve all options and their values.
 437 If \fIoptionName\fR is not NULL, it is the name of the
 438 option to query; the option's value is copied to the Tcl dynamic string
 439 denoted by \fIoptionValue\fR. If
 440 \fIoptionName\fR is NULL, the function stores an alternating list of option
 441 names and their values in \fIoptionValue\fR, using a series of calls to
 442 \fBTcl_DStringAppendElement\fR. The various preexisting options and
 443 their possible values are described in the manual entry for the Tcl
 444 \fBfconfigure\fR command. Other options can be added by each channel type.
 445 These channel type specific options are described in the manual entry for
 446 the Tcl command that creates a channel of that type; for example, the
 447 additional options for TCP based channels are described in the manual entry
 448 for the Tcl \fBsocket\fR command.
 449 The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
 450 \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
 451 error code.
 452
 453 .SH TCL_SETCHANNELOPTION
 454 .PP
 455 \fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
 456 \fIOptionName\fR is the option to set and \fInewValue\fR is the value to
 457 set.
 458 The procedure normally returns \fBTCL_OK\fR.  If an error occurs,
 459 it returns \fBTCL_ERROR\fR;  in addition, if \fIinterp\fR is non-NULL,
 460 \fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR.
 461
 462 .SH TCL_EOF
 463 .PP
 464 \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
 465 an end of file during the last input operation.
 466
 467 .SH TCL_INPUTBLOCKED
 468 .PP
 469 \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
 470 nonblocking mode and the last input operation returned less data than
 471 requested because there was insufficient data available.
 472 The call always returns zero if the channel is in blocking mode.
 473
 474 .SH TCL_INPUTBUFFERED
 475 .PP
 476 \fBTcl_InputBuffered\fR returns the number of bytes of input currently
 477 buffered in the internal buffers for a channel. If the channel is not open
 478 for reading, this function always returns zero.
 479
 480 .VS
 481 .SH "PLATFORM ISSUES"
 482 .PP
 483 The handles returned from \fBTcl_GetChannelHandle\fR depend on the
 484 platform and the channel type.  On Unix platforms, the handle is
 485 always a Unix file descriptor as returned from the \fBopen\fR system
 486 call.  On Windows platforms, the handle is a file \fBHANDLE\fR when
 487 the channel was created with \fBTcl_OpenFileChannel\fR,
 488 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR.  Other
 489 channel types may return a different type of handle on Windows
 490 platforms.  On the Macintosh platform, the handle is a file reference
 491 number as returned from \fBHOpenDF\fR.
 492 .VE
 493
 494 .SH "SEE ALSO"
 495 DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
 496
 497 .SH KEYWORDS
 498 access point, blocking, buffered I/O, channel, channel driver, end of file,
 499 flush, input, nonblocking, output, read, seek, write