2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" SCCS: @(#) OpenFileChnl.3 1.40 97/09/29 11:22:49
8 '\" The definitions below are for supplemental macros used in Tcl/Tk
11 '\" .AP type name in/out ?indent?
12 '\" Start paragraph describing an argument to a library procedure.
13 '\" type is type of argument (int, etc.), in/out is either "in", "out",
14 '\" or "in/out" to describe whether procedure reads or modifies arg,
15 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 '\" needed; use .AS below instead)
19 '\" Give maximum sizes of arguments for setting tab stops. Type and
20 '\" name are examples of largest possible arguments that will be passed
21 '\" to .AP later. If args are omitted, default tab stops are used.
24 '\" Start box enclosure. From here until next .BE, everything will be
25 '\" enclosed in one large box.
28 '\" End of box enclosure.
31 '\" Begin code excerpt.
36 '\" .VS ?version? ?br?
37 '\" Begin vertical sidebar, for use in marking newly-changed parts
38 '\" of man pages. The first argument is ignored and used for recording
39 '\" the version when the .VS was added, so that the sidebars can be
40 '\" found and removed when they reach a certain age. If another argument
41 '\" is present, then a line break is forced before starting the sidebar.
44 '\" End of vertical sidebar.
47 '\" Begin an indented unfilled display.
50 '\" End of indented unfilled display.
53 '\" Start of list of standard options for a Tk widget. The
54 '\" options follow on successive lines, in four columns separated
58 '\" End of list of standard options for a Tk widget.
60 '\" .OP cmdName dbName dbClass
61 '\" Start of description of a specific option. cmdName gives the
62 '\" option's name as specified in the class command, dbName gives
63 '\" the option's name in the option database, and dbClass gives
64 '\" the option's class in the option database.
67 '\" Print arg1 underlined, then print arg2 normally.
69 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
71 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
75 '\" # Start an argument description
79 . ie !"\\$2"" .TP \\n()Cu
84 \&\\$1 \\fI\\$2\\fP (\\$3)
97 '\" # define tabbing values for .AP
100 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
103 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
104 .nr )C \\n()Bu+\\w'(in/out)'u+2n
106 .AS Tcl_Interp Tcl_CreateInterp in/out
107 '\" # BS - start boxed text
108 '\" # ^y = starting y location
116 .if n \l'\\n(.lu\(ul'
119 '\" # BE - end boxed text (draw box now)
124 .ie n \l'\\n(^lu\(ul'
126 .\" Draw four-sided box normally, but don't draw top of
127 .\" box if the box started on an earlier page.
129 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
132 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 '\" # VS - start vertical sidebar
140 '\" # ^Y = starting y location
141 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
145 .ie n 'mc \s12\(br\s0
148 '\" # VE - end of vertical sidebar
156 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
163 '\" # Special macro to handle page bottom: finish off current
164 '\" # box/sidebar if in box/sidebar mode, then invoked standard
165 '\" # page bottom macro.
172 .\" Draw three-sided box if this is the box's first page,
173 .\" draw two sides but no top otherwise.
174 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
175 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
178 .nr ^x \\n(^tu+1v-\\n(^Yu
179 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
192 '\" # DS - begin display
198 '\" # DE - end display
204 '\" # SO - start of list of standard options
206 .SH "STANDARD OPTIONS"
212 '\" # SE - end of list of standard options
217 See the \\fBoptions\\fR manual entry for details on the standard options.
219 '\" # OP - start of full description for a single option
224 Command-Line Name: \\fB\\$1\\fR
225 Database Name: \\fB\\$2\\fR
226 Database Class: \\fB\\$3\\fR
230 '\" # CS - begin code excerpt
236 '\" # CE - end code excerpt
244 .TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
246 '\" Note: do not modify the .SH NAME line immediately below!
248 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
251 \fB#include <tcl.h>\fR
253 typedef ... Tcl_Channel;
256 \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
259 \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
263 \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
267 \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
270 \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
273 \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
276 \fBTcl_Close\fR(\fIinterp, channel\fR)
279 \fBTcl_Read\fR(\fIchannel, buf, toRead\fR)
282 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
285 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
288 \fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
291 \fBTcl_Flush\fR(\fIchannel\fR)
294 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
297 \fBTcl_Tell\fR(\fIchannel\fR)
300 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
303 \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
306 \fBTcl_Eof\fR(\fIchannel\fR)
309 \fBTcl_InputBlocked\fR(\fIchannel\fR)
312 \fBTcl_InputBuffered\fR(\fIchannel\fR)
315 .AS Tcl_ChannelType newClientProcPtr in
316 .AP Tcl_Interp *interp in
317 Used for error reporting and to look up a channel registered in it.
318 .AP char *fileName in
319 The name of a local or network file.
321 Specifies how the file is to be accessed. May have any of the
322 values allowed for the \fImode\fR argument to the Tcl
324 For \fBTcl_OpenCommandChannel\fR, may be NULL.
325 .AP int permissions in
326 POSIX-style permission flags such as 0644.
327 If a new file is created, these permissions will be set on the
330 The number of elements in \fIargv\fR.
332 Arguments for constructing a command pipeline.
333 These values have the same meaning as the non-switch arguments
334 to the Tcl \fBexec\fR command.
336 Specifies the disposition of the stdio handles in pipeline: OR-ed
337 combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR,
338 and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for
339 the first child in the pipe is the pipe channel, otherwise it is the same
340 as the standard input of the invoking process; likewise for
341 \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set,
342 then the pipe can redirect stdio handles to override the stdio handles for
343 which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
344 If it is set, then such redirections cause an error.
346 .AP ClientData handle in
347 Operating system specific handle for I/O to a file. For Unix this is a
348 file descriptor, for Windows it is a HANDLE.
349 .AP int readOrWrite in
350 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
351 what operations are valid on \fIhandle\fR.
354 Points at an integer variable that will receive an OR-ed combination of
355 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
356 open for reading and writing.
357 .AP Tcl_Channel channel in
358 A Tcl channel for input or output. Must have been the return value
359 from a procedure such as \fBTcl_OpenFileChannel\fR.
361 An array of bytes in which to store channel input, or from which
362 to read channel output.
364 The length of the input or output.
366 If nonzero, store the input at the end of the input queue, otherwise store
367 it at the head of the input queue.
369 The number of bytes to read from the channel.
370 .AP Tcl_DString *lineRead in
371 A pointer to a Tcl dynamic string in which to store the line read from the
372 channel. Must have been initialized by the caller. The line read
373 will be appended to any data already in the dynamic string.
374 .AP Tcl_Obj *linePtrObj in
375 A pointer to a Tcl object in which to store the line read from the
376 channel. The line read will be appended to the current value of the
379 The number of bytes to read from \fIbuf\fR and output to the channel.
381 How far to move the access point in the channel at which the next input or
382 output operation will be applied, measured in bytes from the position
383 given by \fIseekMode\fR. May be either positive or negative.
385 Relative to which point to seek; used with \fIoffset\fR to calculate the new
386 access point for the channel. Legal values are \fBSEEK_SET\fR,
387 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
388 .AP char *optionName in
389 The name of an option applicable to this channel, such as \fB\-blocking\fR.
390 May have any of the values accepted by the \fBfconfigure\fR command.
391 .AP Tcl_DString *optionValue in
392 Where to store the value of an option or a list of all options and their
393 values. Must have been initialized by the caller.
394 .AP char *newValue in
395 New value for the option given by \fIoptionName\fR.
400 The Tcl channel mechanism provides a device-independent and
401 platform-independent mechanism for performing buffered input
402 and output operations on a variety of file, socket, and device
404 The channel mechanism is extensible to new channel types, by
405 providing a low level channel driver for the new type; the channel driver
406 interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
407 channel mechanism provides a buffering scheme modelled after
408 Unix's standard I/O, and it also allows for nonblocking I/O on
411 The procedures described in this manual entry comprise the C APIs of the
412 generic layer of the channel architecture. For a description of the channel
413 driver architecture and how to implement channel drivers for new types of
414 channels, see the manual entry for \fBTcl_CreateChannel\fR.
416 .SH TCL_OPENFILECHANNEL
418 \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
419 returns a channel handle that can be used to perform input and output on
420 the file. This API is modelled after the \fBfopen\fR procedure of
421 the Unix standard I/O library.
422 The syntax and meaning of all arguments is similar to those
423 given in the Tcl \fBopen\fR command when opening a file.
424 If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
425 returns NULL and records a POSIX error code that can be
426 retrieved with \fBTcl_GetErrno\fR.
427 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
428 leaves an error message in \fIinterp->result\fR after any error.
430 The newly created channel is not registered in the supplied interpreter; to
431 register it, use \fBTcl_RegisterChannel\fR, described below.
432 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
433 previously closed, the act of creating the new channel also assigns it as a
434 replacement for the standard channel.
436 .SH TCL_OPENCOMMANDCHANNEL
438 \fBTcl_OpenCommandChannel\fR provides a C-level interface to the
439 functions of the \fBexec\fR and \fBopen\fR commands.
440 It creates a sequence of subprocesses specified
441 by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
442 be used to communicate with these subprocesses.
443 The \fIflags\fR argument indicates what sort of communication will
444 exist with the command pipeline.
446 If the \fBTCL_STDIN\fR flag is set then the standard input for the
447 first subprocess will be tied to the channel: writing to the channel
448 will provide input to the subprocess. If \fBTCL_STDIN\fR is not set,
449 then standard input for the first subprocess will be the same as this
450 application's standard input. If \fBTCL_STDOUT\fR is set then
451 standard output from the last subprocess can be read from the channel;
452 otherwise it goes to this application's standard output. If
453 \fBTCL_STDERR\fR is set, standard error output for all subprocesses is
454 returned to the channel and results in an error when the channel is
455 closed; otherwise it goes to this application's standard error. If
456 \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
457 redirect the stdio handles to override \fBTCL_STDIN\fR,
458 \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
459 error for argc and argv to override stdio channels for which
460 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
462 If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
463 returns NULL and records a POSIX error code that can be retrieved with
465 In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
466 \fIinterp->result\fR if \fIinterp\fR is not NULL.
468 The newly created channel is not registered in the supplied interpreter; to
469 register it, use \fBTcl_RegisterChannel\fR, described below.
470 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
471 previously closed, the act of creating the new channel also assigns it as a
472 replacement for the standard channel.
474 .SH TCL_MAKEFILECHANNEL
476 \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
477 platform-specific, file handle.
478 The newly created channel is not registered in the supplied interpreter; to
479 register it, use \fBTcl_RegisterChannel\fR, described below.
480 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
481 previously closed, the act of creating the new channel also assigns it as a
482 replacement for the standard channel.
486 \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
487 create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
488 \fIinterp\fR. If a channel by that name is not registered in that interpreter,
489 the procedure returns NULL. If the \fImode\fR argument is not NULL, it
490 points at an integer variable that will receive an OR-ed combination of
491 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
492 open for reading and writing.
494 .SH TCL_REGISTERCHANNEL
496 \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
497 in \fIinterp\fR. After this call, Tcl programs executing in that
498 interpreter can refer to the channel in input or output operations using
499 the name given in the call to \fBTcl_CreateChannel\fR. After this call,
500 the channel becomes the property of the interpreter, and the caller should
501 not call \fBTcl_Close\fR for the channel; the channel will be closed
502 automatically when it is unregistered from the interpreter.
504 Code executing outside of any Tcl interpreter can call
505 \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
506 wishes to hold a reference to this channel. Subsequently, the channel can
507 be registered in a Tcl interpreter and it will only be closed when the
508 matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
509 This allows code executing outside of any interpreter to safely hold a
510 reference to a channel that is also registered in a Tcl interpreter.
512 .SH TCL_UNREGISTERCHANNEL
514 \fBTcl_UnregisterChannel\fR removes a channel from the set of channels
515 accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
516 able to use the channel's name to refer to the channel in that interpreter.
517 If this operation removed the last registration of the channel in any
518 interpreter, the channel is also closed and destroyed.
520 Code not associated with a Tcl interpreter can call
521 \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
522 that it no longer holds a reference to that channel. If this is the last
523 reference to the channel, it will now be closed.
527 \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
528 currently open channel. The channel should not be registered in any
529 interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
530 the channel's output device prior to destroying the channel, and any
531 buffered input is discarded. If this is a blocking channel, the call does
532 not return until all buffered data is successfully sent to the channel's
533 output device. If this is a nonblocking channel and there is buffered
534 output that cannot be written without blocking, the call returns
535 immediately; output is flushed in the background and the channel will be
536 closed once all of the buffered data has been output. In this case errors
537 during flushing are not reported.
539 If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
540 If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
541 POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
542 If the channel is being closed synchronously and an error occurs during
543 closing of the channel and \fIinterp\fR is not NULL, an error message is
544 left in \fIinterp->result\fR.
546 Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
547 registered using \fBTcl_RegisterChannel\fR; see the documentation for
548 \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
549 given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
550 you should instead use \fBTcl_UnregisterChannel\fR, which will internally
551 call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
552 matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
556 \fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from
557 \fIchannel\fR and stores it at \fIbuf\fR.
558 The return value of \fBTcl_Read\fR is the number of characters written
560 The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents
561 are valid from the zeroth position up to and excluding the position
562 indicated by the return value.
563 If an error occurs, the return value is -1 and \fBTcl_Read\fR records
564 a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
566 The return value may be smaller than the value of \fItoRead\fR, indicating
567 that less data than requested was available, also called a \fIshort
569 In blocking mode, this can only happen on an end-of-file.
570 In nonblocking mode, a short read can also occur if there is not
571 enough input currently available: \fBTcl_Read\fR returns a short
572 count rather than waiting for more data.
574 If the channel is in blocking mode, a return value of zero indicates an end
575 of file condition. If the channel is in nonblocking mode, a return value of
576 zero indicates either that no input is currently available or an end of
577 file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR
578 to tell which of these conditions actually occurred.
580 \fBTcl_Read\fR translates platform-specific end-of-line representations
581 into the canonical \fB\en\fR internal representation according to the
582 current end-of-line recognition mode. End-of-line recognition and the
583 various platform-specific modes are described in the manual entry for the
584 Tcl \fBfconfigure\fR command.
586 .SH TCL_GETS AND TCL_GETSOBJ
588 \fBTcl_Gets\fR reads a line of input from a channel and appends all of
589 the characters of the line except for the terminating end-of-line character(s)
590 to the dynamic string given by \fIdsPtr\fR.
591 The end-of-line character(s) are read and discarded.
593 If a line was successfully read, the return value is greater than or
594 equal to zero, and it indicates the number of characters stored
595 in the dynamic string.
596 If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error
597 code that can be retrieved with \fBTcl_GetErrno\fR.
598 \fBTcl_Gets\fR also returns -1 if the end of the file is reached;
599 the \fBTcl_Eof\fR procedure can be used to distinguish an error
600 from an end-of-file condition.
602 If the channel is in nonblocking mode, the return value can also
603 be -1 if no data was available or the data that was available
604 did not contain an end-of-line character.
605 When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
606 invoked to determine if the channel is blocked because of input
609 \fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
610 characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
614 \fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
615 on \fIchannel\fR. This data may not appear on the output device
616 immediately. If the data should appear immediately, call \fBTcl_Flush\fR
617 after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on
618 the channel to \fBnone\fR. If you wish the data to appear as soon as an end
619 of line is accepted for output, set the \fB\-buffering\fR option on the
620 channel to \fBline\fR mode.
622 The \fItoWrite\fR argument specifies how many bytes of data are provided in
623 the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data
624 to be NULL terminated and it outputs everything up to the NULL.
626 The return value of \fBTcl_Write\fR is a count of how many
627 characters were accepted for output to the channel. This is either equal to
628 \fItoWrite\fR or -1 to indicate that an error occurred.
629 If an error occurs, \fBTcl_Write\fR also records a POSIX error code
630 that may be retrieved with \fBTcl_GetErrno\fR.
632 Newline characters in the output data are translated to platform-specific
633 end-of-line sequences according to the \fB\-translation\fR option for
638 \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
639 to be written to its underlying file or device as soon as possible.
640 If the channel is in blocking mode, the call does not return until
641 all the buffered data has been sent to the channel or some error occurred.
642 The call returns immediately if the channel is nonblocking; it starts
643 a background flush that will write the buffered data to the channel
644 eventually, as fast as the channel is able to absorb it.
646 The return value is normally \fBTCL_OK\fR.
647 If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
648 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
652 \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
653 data will be read or written. Buffered output is flushed to the channel and
654 buffered input is discarded, prior to the seek operation.
656 \fBTcl_Seek\fR normally returns the new access point.
657 If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error
658 code that can be retrieved with \fBTcl_GetErrno\fR.
659 After an error, the access point may or may not have been moved.
663 \fBTcl_Tell\fR returns the current access point for a channel. The returned
664 value is -1 if the channel does not support seeking.
666 .SH TCL_GETCHANNELOPTION
668 \fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
669 the options currently in effect for a channel, or a list of all options and
670 their values. The \fIchannel\fR argument identifies the channel for which
671 to query an option or retrieve all options and their values.
672 If \fIoptionName\fR is not NULL, it is the name of the
673 option to query; the option's value is copied to the Tcl dynamic string
674 denoted by \fIoptionValue\fR. If
675 \fIoptionName\fR is NULL, the function stores an alternating list of option
676 names and their values in \fIoptionValue\fR, using a series of calls to
677 \fBTcl_DStringAppendElement\fR. The various preexisting options and
678 their possible values are described in the manual entry for the Tcl
679 \fBfconfigure\fR command. Other options can be added by each channel type.
680 These channel type specific options are described in the manual entry for
681 the Tcl command that creates a channel of that type; for example, the
682 additional options for TCP based channels are described in the manual entry
683 for the Tcl \fBsocket\fR command.
684 The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
685 \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
688 .SH TCL_SETCHANNELOPTION
690 \fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
691 \fIOptionName\fR is the option to set and \fInewValue\fR is the value to
693 The procedure normally returns \fBTCL_OK\fR. If an error occurs,
694 it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
695 \fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR.
699 \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
700 an end of file during the last input operation.
704 \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
705 nonblocking mode and the last input operation returned less data than
706 requested because there was insufficient data available.
707 The call always returns zero if the channel is in blocking mode.
709 .SH TCL_INPUTBUFFERED
711 \fBTcl_InputBuffered\fR returns the number of bytes of input currently
712 buffered in the internal buffers for a channel. If the channel is not open
713 for reading, this function always returns zero.
716 .SH "PLATFORM ISSUES"
718 The handles returned from \fBTcl_GetChannelHandle\fR depend on the
719 platform and the channel type. On Unix platforms, the handle is
720 always a Unix file descriptor as returned from the \fBopen\fR system
721 call. On Windows platforms, the handle is a file \fBHANDLE\fR when
722 the channel was created with \fBTcl_OpenFileChannel\fR,
723 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
724 channel types may return a different type of handle on Windows
725 platforms. On the Macintosh platform, the handle is a file reference
726 number as returned from \fBHOpenDF\fR.
730 DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
733 access point, blocking, buffered I/O, channel, channel driver, end of file,
734 flush, input, nonblocking, output, read, seek, write
OSDN Git Service
