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 '\" RCS: @(#) $Id: OpenFileChnl.3,v 1.9 2000/04/25 00:54:53 ericm Exp $
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 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
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.3 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_GetChannelNames, Tcl_GetChannelNamesEx, 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, Tcl_Ungets \- 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)
271 \fBTcl_GetChannelNames\fR(\fIinterp\fR)
274 \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR)
278 \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
281 \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
284 \fBTcl_Close\fR(\fIinterp, channel\fR)
288 \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
291 \fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR)
294 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
297 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
300 \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR)
303 \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
306 \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
309 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
313 \fBTcl_Eof\fR(\fIchannel\fR)
316 \fBTcl_Flush\fR(\fIchannel\fR)
319 \fBTcl_InputBlocked\fR(\fIchannel\fR)
322 \fBTcl_InputBuffered\fR(\fIchannel\fR)
325 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
328 \fBTcl_Tell\fR(\fIchannel\fR)
331 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
334 \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
337 .AS Tcl_ChannelType newClientProcPtr in
338 .AP Tcl_Interp *interp in
339 Used for error reporting and to look up a channel registered in it.
340 .AP char *fileName in
341 The name of a local or network file.
343 Specifies how the file is to be accessed. May have any of the values
344 allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. For
345 \fBTcl_OpenCommandChannel\fR, may be NULL.
346 .AP int permissions in
347 POSIX-style permission flags such as 0644. If a new file is created, these
348 permissions will be set on the created file.
350 The number of elements in \fIargv\fR.
352 Arguments for constructing a command pipeline. These values have the same
353 meaning as the non-switch arguments to the Tcl \fBexec\fR command.
355 Specifies the disposition of the stdio handles in pipeline: OR-ed
356 combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and
357 \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child
358 in the pipe is the pipe channel, otherwise it is the same as the standard
359 input of the invoking process; likewise for \fBTCL_STDOUT\fR and
360 \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can
361 redirect stdio handles to override the stdio handles for which
362 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it
363 is set, then such redirections cause an error.
365 .AP ClientData handle in
366 Operating system specific handle for I/O to a file. For Unix this is a
367 file descriptor, for Windows it is a HANDLE.
368 .AP int readOrWrite in
369 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
370 what operations are valid on \fIhandle\fR.
371 .AP char *channelName in
372 The name of the channel.
375 Points at an integer variable that will receive an OR-ed combination of
376 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
377 open for reading and writing.
378 .AP Tcl_Channel channel in
379 A Tcl channel for input or output. Must have been the return value
380 from a procedure such as \fBTcl_OpenFileChannel\fR.
382 .AP Tcl_Obj *readObjPtr in/out
383 A pointer to a Tcl Object in which to store the characters read from the
385 .AP int charsToRead in
386 The number of characters to read from the channel. If the channel's encoding
387 is \fBbinary\fR, this is equivalent to the number of bytes to read from the
389 .AP int appendFlag in
390 If non-zero, data read from the channel will be appended to the object.
391 Otherwise, the data will replace the existing contents of the object.
392 .AP char *readBuf out
393 A buffer in which to store the bytes read from the channel.
394 .AP int bytesToRead in
395 The number of bytes to read from the channel. The buffer \fIreadBuf\fR must
396 be large enough to hold this many bytes.
397 .AP Tcl_Obj *lineObjPtr in/out
398 A pointer to a Tcl object in which to store the line read from the
399 channel. The line read will be appended to the current value of the
401 .AP Tcl_DString *lineRead in/out
402 A pointer to a Tcl dynamic string in which to store the line read from the
403 channel. Must have been initialized by the caller. The line read will be
404 appended to any data already in the dynamic string.
405 .AP Tcl_Obj *writeObjPtr in
406 A pointer to a Tcl Object whose contents will be output to the channel.
407 .AP "CONST char" *charBuf in
408 A buffer containing the characters to output to the channel.
410 A buffer containing the bytes to output to the channel.
411 .AP int bytesToWrite in
412 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
413 output to the channel.
416 How far to move the access point in the channel at which the next input or
417 output operation will be applied, measured in bytes from the position
418 given by \fIseekMode\fR. May be either positive or negative.
420 Relative to which point to seek; used with \fIoffset\fR to calculate the new
421 access point for the channel. Legal values are \fBSEEK_SET\fR,
422 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
423 .AP char *optionName in
424 The name of an option applicable to this channel, such as \fB\-blocking\fR.
425 May have any of the values accepted by the \fBfconfigure\fR command.
426 .AP Tcl_DString *optionValue in
427 Where to store the value of an option or a list of all options and their
428 values. Must have been initialized by the caller.
429 .AP char *newValue in
430 New value for the option given by \fIoptionName\fR.
433 The pattern to match on, passed to Tcl_StringMatch, or NULL.
435 The input to add to a channel buffer.
439 Flag indicating whether the input should be added to the end or
440 beginning of the channel buffer.
446 The Tcl channel mechanism provides a device-independent and
447 platform-independent mechanism for performing buffered input
448 and output operations on a variety of file, socket, and device
450 The channel mechanism is extensible to new channel types, by
451 providing a low level channel driver for the new type; the channel driver
452 interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
453 channel mechanism provides a buffering scheme modeled after
454 Unix's standard I/O, and it also allows for nonblocking I/O on
457 The procedures described in this manual entry comprise the C APIs of the
458 generic layer of the channel architecture. For a description of the channel
459 driver architecture and how to implement channel drivers for new types of
460 channels, see the manual entry for \fBTcl_CreateChannel\fR.
462 .SH TCL_OPENFILECHANNEL
464 \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
465 returns a channel handle that can be used to perform input and output on
466 the file. This API is modeled after the \fBfopen\fR procedure of
467 the Unix standard I/O library.
468 The syntax and meaning of all arguments is similar to those
469 given in the Tcl \fBopen\fR command when opening a file.
470 If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
471 returns NULL and records a POSIX error code that can be
472 retrieved with \fBTcl_GetErrno\fR.
473 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
474 leaves an error message in \fIinterp\fR's result after any error.
476 The newly created channel is not registered in the supplied interpreter; to
477 register it, use \fBTcl_RegisterChannel\fR, described below.
478 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
479 previously closed, the act of creating the new channel also assigns it as a
480 replacement for the standard channel.
482 .SH TCL_OPENCOMMANDCHANNEL
484 \fBTcl_OpenCommandChannel\fR provides a C-level interface to the
485 functions of the \fBexec\fR and \fBopen\fR commands.
486 It creates a sequence of subprocesses specified
487 by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
488 be used to communicate with these subprocesses.
489 The \fIflags\fR argument indicates what sort of communication will
490 exist with the command pipeline.
492 If the \fBTCL_STDIN\fR flag is set then the standard input for the
493 first subprocess will be tied to the channel: writing to the channel
494 will provide input to the subprocess. If \fBTCL_STDIN\fR is not set,
495 then standard input for the first subprocess will be the same as this
496 application's standard input. If \fBTCL_STDOUT\fR is set then
497 standard output from the last subprocess can be read from the channel;
498 otherwise it goes to this application's standard output. If
499 \fBTCL_STDERR\fR is set, standard error output for all subprocesses is
500 returned to the channel and results in an error when the channel is
501 closed; otherwise it goes to this application's standard error. If
502 \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
503 redirect the stdio handles to override \fBTCL_STDIN\fR,
504 \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
505 error for argc and argv to override stdio channels for which
506 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
508 If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
509 returns NULL and records a POSIX error code that can be retrieved with
511 In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
512 the interpreter's result if \fIinterp\fR is not NULL.
514 The newly created channel is not registered in the supplied interpreter; to
515 register it, use \fBTcl_RegisterChannel\fR, described below.
516 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
517 previously closed, the act of creating the new channel also assigns it as a
518 replacement for the standard channel.
520 .SH TCL_MAKEFILECHANNEL
522 \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
523 platform-specific, file handle.
524 The newly created channel is not registered in the supplied interpreter; to
525 register it, use \fBTcl_RegisterChannel\fR, described below.
526 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
527 previously closed, the act of creating the new channel also assigns it as a
528 replacement for the standard channel.
532 \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
533 create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
534 \fIinterp\fR. If a channel by that name is not registered in that interpreter,
535 the procedure returns NULL. If the \fImode\fR argument is not NULL, it
536 points at an integer variable that will receive an OR-ed combination of
537 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
538 open for reading and writing.
540 \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the
541 names of the registered channels to the interpreter's result as a
542 list object. \fBTcl_GetChannelNamesEx\fR will filter these names
543 according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it
544 will not do any filtering. The return value is \fBTCL_OK\fR if no
545 errors occured writing to the result, otherwise it is \fBTCL_ERROR\fR,
546 and the error message is left in the interpreter's result.
548 .SH TCL_REGISTERCHANNEL
550 \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
551 in \fIinterp\fR. After this call, Tcl programs executing in that
552 interpreter can refer to the channel in input or output operations using
553 the name given in the call to \fBTcl_CreateChannel\fR. After this call,
554 the channel becomes the property of the interpreter, and the caller should
555 not call \fBTcl_Close\fR for the channel; the channel will be closed
556 automatically when it is unregistered from the interpreter.
558 Code executing outside of any Tcl interpreter can call
559 \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
560 wishes to hold a reference to this channel. Subsequently, the channel can
561 be registered in a Tcl interpreter and it will only be closed when the
562 matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
563 This allows code executing outside of any interpreter to safely hold a
564 reference to a channel that is also registered in a Tcl interpreter.
566 .SH TCL_UNREGISTERCHANNEL
568 \fBTcl_UnregisterChannel\fR removes a channel from the set of channels
569 accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
570 able to use the channel's name to refer to the channel in that interpreter.
571 If this operation removed the last registration of the channel in any
572 interpreter, the channel is also closed and destroyed.
574 Code not associated with a Tcl interpreter can call
575 \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
576 that it no longer holds a reference to that channel. If this is the last
577 reference to the channel, it will now be closed.
581 \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
582 currently open channel. The channel should not be registered in any
583 interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
584 the channel's output device prior to destroying the channel, and any
585 buffered input is discarded. If this is a blocking channel, the call does
586 not return until all buffered data is successfully sent to the channel's
587 output device. If this is a nonblocking channel and there is buffered
588 output that cannot be written without blocking, the call returns
589 immediately; output is flushed in the background and the channel will be
590 closed once all of the buffered data has been output. In this case errors
591 during flushing are not reported.
593 If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
594 If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
595 POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
596 If the channel is being closed synchronously and an error occurs during
597 closing of the channel and \fIinterp\fR is not NULL, an error message is
598 left in the interpreter's result.
600 Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
601 registered using \fBTcl_RegisterChannel\fR; see the documentation for
602 \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever
603 been given as the \fBchan\fR argument in a call to
604 \fBTcl_RegisterChannel\fR, you should instead use
605 \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR
606 when all calls to \fBTcl_RegisterChannel\fR have been matched by
607 corresponding calls to \fBTcl_UnregisterChannel\fR.
610 .SH "TCL_READCHARS AND TCL_READ"
612 \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
613 to UTF-8 based on the channel's encoding and storing the produced data in
614 \fIreadObjPtr\fR's string representation. The return value of
615 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
616 that were stored in \fIobjPtr\fR. If an error occurs while reading, the
617 return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
618 can be retrieved with \fBTcl_GetErrno\fR.
620 The return value may be smaller than the value to read, indicating that less
621 data than requested was available. This is called a \fIshort read\fR. In
622 blocking mode, this can only happen on an end-of-file. In nonblocking mode,
623 a short read can also occur if there is not enough input currently
624 available: \fBTcl_ReadChars\fR returns a short count rather than waiting
627 If the channel is in blocking mode, a return value of zero indicates an
628 end-of-file condition. If the channel is in nonblocking mode, a return
629 value of zero indicates either that no input is currently available or an
630 end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell
631 which of these conditions actually occurred.
633 \fBTcl_ReadChars\fR translates the various end-of-line representations into
634 the canonical \fB\en\fR internal representation according to the current
635 end-of-line recognition mode. End-of-line recognition and the various
636 platform-specific modes are described in the manual entry for the Tcl
637 \fBfconfigure\fR command.
639 As a performance optimization, when reading from a channel with the encoding
640 \fBbinary\fR, the bytes are not converted to UTF-8 as they are read.
641 Instead, they are stored in \fIreadObjPtr\fR's internal representation as a
642 byte-array object. The string representation of this object will only be
643 constructed if it is needed (e.g., because of a call to
644 \fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read
645 from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
646 related functions, and then written to a channel without the expense of ever
647 converting to or from UTF-8.
649 \fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do
650 encoding conversions, regardless of the channel's encoding. It is deprecated
651 and exists for backwards compatibility with non-internationalized Tcl
652 extensions. It consumes bytes from \fIchannel\fR and stores them in
653 \fIbuf\fR, performing end-of-line translations on the way. The return value
654 of \fBTcl_Read\fR is the number of bytes, up to \fItoRead\fR, written in
655 \fIbuf\fR. The buffer produced by \fBTcl_Read\fR is not NULL terminated.
656 Its contents are valid from the zeroth position up to and excluding the
657 position indicated by the return value.
659 .SH "TCL_GETSOBJ AND TCL_GETS"
661 \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to
662 UTF-8 based on the channel's encoding, until a full line of input has been
663 seen. If the channel's encoding is \fBbinary\fR, each byte read from the
664 channel is treated as an individual Unicode character. All of the
665 characters of the line except for the terminating end-of-line character(s)
666 are appended to \fIlineObjPtr\fR's string representation. The end-of-line
667 character(s) are read and discarded.
669 If a line was successfully read, the return value is greater than or equal
670 to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an
671 error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code
672 that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also
673 returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure
674 can be used to distinguish an error from an end-of-file condition.
676 If the channel is in nonblocking mode, the return value can also be \-1 if
677 no data was available or the data that was available did not contain an
678 end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR
679 procedure may be invoked to determine if the channel is blocked because
680 of input unavailability.
682 \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
683 characters are appended to the appended to the dynamic string given by
684 \fIdsPtr\fR rather than a Tcl object.
688 \fBTcl_Ungets\fR is used to add data to the input queue of a channel,
689 at either the head or tail of the queue. \fIInput\fR is a pointer to
690 the data that is to be added. \fIInputLen\fR gives the length of the
691 input to add. \fIAddAtEnd\fR, in non-zero, indicates that the data is
692 to be added at the end of queue; otherwise it will be added at the
693 head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be
694 added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or
695 -1 if an error occurs.
697 .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
699 \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at
700 \fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the
701 channel's encoding and queued for output to \fIchannel\fR. If
702 \fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR
703 to be NULL terminated and it outputs everything up to the NULL.
705 Data queued for output may not appear on the output device immediately, due
706 to internal buffering. If the data should appear immediately, call
707 \fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the
708 \fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data
709 to appear as soon as a complete line is accepted for output, set the
710 \fB\-buffering\fR option on the channel to \fBline\fR mode.
712 The return value of \fBTcl_WriteChars\fR is a count of how many bytes were
713 accepted for output to the channel. This is either greater than zero to
714 indicate success or \-1 to indicate that an error occurred. If an error
715 occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be
716 retrieved with \fBTcl_GetErrno\fR.
718 Newline characters in the output data are translated to platform-specific
719 end-of-line sequences according to the \fB\-translation\fR option for the
720 channel. This is done even if the channel has no encoding.
722 \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it
723 accepts a Tcl object whose contents will be output to the channel. The
724 UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted
725 to the channel's encoding and queued for output to \fIchannel\fR.
726 As a performance optimization, when writing to a channel with the encoding
727 \fBbinary\fR, UTF-8 characters are not converted as they are written.
728 Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a
729 byte-array object are written to the channel. The byte-array representation
730 of the object will be constructed if it is needed. In this way,
731 byte-oriented data can be read from a channel, manipulated by calling
732 \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
733 channel without the expense of ever converting to or from UTF-8.
735 \fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do
736 encoding conversions, regardless of the channel's encoding. It is
737 deprecated and exists for backwards compatibility with non-internationalized
738 Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at
739 \fIbyteBuf\fR and queues them for output to \fIchannel\fR. If
740 \fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be
741 NULL terminated and it outputs everything up to the NULL.
746 \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
747 to be written to its underlying file or device as soon as possible.
748 If the channel is in blocking mode, the call does not return until
749 all the buffered data has been sent to the channel or some error occurred.
750 The call returns immediately if the channel is nonblocking; it starts
751 a background flush that will write the buffered data to the channel
752 eventually, as fast as the channel is able to absorb it.
754 The return value is normally \fBTCL_OK\fR.
755 If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
756 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
760 \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
761 data will be read or written. Buffered output is flushed to the channel and
762 buffered input is discarded, prior to the seek operation.
764 \fBTcl_Seek\fR normally returns the new access point.
765 If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error
766 code that can be retrieved with \fBTcl_GetErrno\fR.
767 After an error, the access point may or may not have been moved.
771 \fBTcl_Tell\fR returns the current access point for a channel. The returned
772 value is \-1 if the channel does not support seeking.
774 .SH TCL_GETCHANNELOPTION
776 \fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
777 the options currently in effect for a channel, or a list of all options and
778 their values. The \fIchannel\fR argument identifies the channel for which
779 to query an option or retrieve all options and their values.
780 If \fIoptionName\fR is not NULL, it is the name of the
781 option to query; the option's value is copied to the Tcl dynamic string
782 denoted by \fIoptionValue\fR. If
783 \fIoptionName\fR is NULL, the function stores an alternating list of option
784 names and their values in \fIoptionValue\fR, using a series of calls to
785 \fBTcl_DStringAppendElement\fR. The various preexisting options and
786 their possible values are described in the manual entry for the Tcl
787 \fBfconfigure\fR command. Other options can be added by each channel type.
788 These channel type specific options are described in the manual entry for
789 the Tcl command that creates a channel of that type; for example, the
790 additional options for TCP based channels are described in the manual entry
791 for the Tcl \fBsocket\fR command.
792 The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
793 \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
796 .SH TCL_SETCHANNELOPTION
798 \fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
799 \fIOptionName\fR is the option to set and \fInewValue\fR is the value to
801 The procedure normally returns \fBTCL_OK\fR. If an error occurs,
802 it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
803 \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result.
807 \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
808 an end of file during the last input operation.
812 \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
813 nonblocking mode and the last input operation returned less data than
814 requested because there was insufficient data available.
815 The call always returns zero if the channel is in blocking mode.
817 .SH TCL_INPUTBUFFERED
819 \fBTcl_InputBuffered\fR returns the number of bytes of input currently
820 buffered in the internal buffers for a channel. If the channel is not open
821 for reading, this function always returns zero.
824 .SH "PLATFORM ISSUES"
826 The handles returned from \fBTcl_GetChannelHandle\fR depend on the
827 platform and the channel type. On Unix platforms, the handle is
828 always a Unix file descriptor as returned from the \fBopen\fR system
829 call. On Windows platforms, the handle is a file \fBHANDLE\fR when
830 the channel was created with \fBTcl_OpenFileChannel\fR,
831 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
832 channel types may return a different type of handle on Windows
833 platforms. On the Macintosh platform, the handle is a file reference
834 number as returned from \fBHOpenDF\fR.
838 DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
841 access point, blocking, buffered I/O, channel, channel driver, end of file,
842 flush, input, nonblocking, output, read, seek, write
OSDN Git Service
